How to Create Your First MCP Tool on SettleGrid

The fastest way to get started is with the SettleGrid scaffolding CLI. Run npx create-settlegrid-tool in your terminal and follow the interactive prompts. The CLI creates a complete project with TypeScript, billing hooks, and test harnesses already wired in. You can also pass flags like --category data or --pricing per-call to skip the prompts.

If you prefer to add SettleGrid to an existing MCP server, install the SDK directly with npm install @settlegrid/mcp. The SDK exports a withBilling wrapper that intercepts tool calls, meters usage, and settles payments automatically. It works with any MCP server implementation that follows the Model Context Protocol specification.

After installation, verify your setup by running npx settlegrid doctor. This command checks your Node.js version (18+), validates your tsconfig.json settings, and confirms the SDK can reach the SettleGrid API. Fix any warnings before proceeding — they will save you debugging time later.

An MCP tool handler is a function that receives structured input from an AI agent and returns structured output. The SettleGrid SDK wraps this handler with billing logic, but the handler itself is just a regular async function. Start by defining your tool's input schema using Zod (included as a dependency) and writing the handler logic.

For example, a simple data enrichment tool might accept a company domain and return firmographic data. Define the input as z.object({ domain: z.string().url() }) and the handler as an async function that calls your data source and returns the result. The SDK handles serialization, error formatting, and retry logic automatically.

Keep your handler focused on a single capability. MCP tools work best when they do one thing well rather than bundling multiple operations. If you have related capabilities (e.g., lookup and enrich), create separate tool handlers for each. This makes pricing clearer, testing simpler, and lets agents call only what they need.

Pricing is defined in your settlegrid.config.ts file at the project root. The simplest model is per-invocation: set a price in cents and every successful tool call charges that amount. For example, pricing: { model: 'per-call', amount: 5 } charges 5 cents per call. The SDK supports six pricing models: per-call, per-token, per-byte, per-second, tiered (different prices per method), and outcome-based (charge only on success).

For your first tool, start with per-call pricing. It is the easiest to reason about, the simplest to communicate to consumers, and works well for tools with consistent compute costs. You can always switch to a more sophisticated model later — SettleGrid handles the migration transparently and notifies existing consumers of the change.

Set your price based on the value your tool delivers, not just your compute cost. A data enrichment tool that saves an agent 30 seconds of research is worth more than the 0.2 cents of API calls it takes to run. Research comparable tools on the SettleGrid marketplace (/explore) to benchmark your pricing against competitors. Most first-time tool builders underprice by 3-5x.

Before deploying, test your tool end-to-end using the SettleGrid sandbox. Run npx settlegrid sandbox to start a local instance that simulates the full billing pipeline — metering, settlement, webhook delivery — without processing real payments. The sandbox logs every event to your terminal so you can verify each step.

Write integration tests that call your tool through the sandbox and assert on both the response and the billing events. The SDK includes test utilities: createTestClient() creates a pre-authenticated client, and expectBillingEvent() asserts that a specific metering event was recorded. Run your tests with npm test — the scaffolded project includes a Jest configuration that automatically starts and stops the sandbox.

Test edge cases: what happens when your tool receives invalid input, when your upstream API is down, or when the agent sends a request that exceeds your rate limits? The SDK returns structured errors for all of these cases, but verify that your handler doesn't swallow errors or return partial results that could confuse agents. A well-tested tool earns consumer trust and reduces support burden.

Deploy your MCP server to any hosting provider — Vercel, Railway, Fly.io, AWS Lambda, or your own infrastructure. The SettleGrid SDK is runtime-agnostic: it works in Node.js, Deno, and Bun. For serverless deployments, the SDK batches metering events and flushes them asynchronously to avoid adding latency to your responses.

Once deployed, publish your tool to the SettleGrid marketplace by running npx settlegrid publish. This command validates your configuration, creates your tool listing, and submits it for review. Listings go live within minutes and appear in the explore page, category pages, and the Discovery API that AI agents use to find tools.

After publishing, add the SettleGrid badge to your project's README with npx settlegrid badge. The badge shows your tool's pricing, category, and reputation score, and links directly to your marketplace listing. Tools with README badges see 3x more discovery traffic because they are visible to developers browsing GitHub and npm.

Once your tool is live, use the SettleGrid dashboard to monitor usage, revenue, and consumer behavior. The dashboard shows real-time metrics: calls per minute, p50/p95 latency, error rate, revenue by day, and top consumers. Set up alerts for anomalies — a sudden spike in errors or a drop in call volume usually indicates a problem with your upstream dependencies.

Review your pricing after the first week. If your tool has a high adoption rate but low revenue, your price is too low. If adoption is slow despite strong discovery metrics (impressions and clicks), your price may be too high or your tool description needs improvement. The marketplace works best when tools are priced at the sweet spot where agents get clear value and you earn sustainable revenue.

Iterate on your tool based on real usage patterns. The dashboard shows which input parameters agents use most, which errors they encounter, and which methods they call most frequently. Use this data to improve your handler, add new capabilities, and refine your pricing. The best tools on SettleGrid ship updates weekly.