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. Run it interactively, or pass --template <slug> to scaffold a specific gallery template (for example, --template tmdb).

If you prefer to add SettleGrid to an existing MCP server, install the SDK directly with npm install @settlegrid/mcp. You initialize the SDK with settlegrid.init() and wrap your handler with sg.wrap(), which 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, build your project with npm run build and run your test suite to confirm everything is wired up correctly. Fix any errors 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 the pricing option you pass to settlegrid.init(). The simplest model is per-call: set a price in cents and every successful tool call charges that amount. For example, settlegrid.init({ toolSlug: 'my-tool', pricing: { defaultCostCents: 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 with your own unit tests. The handler you pass to sg.wrap() is a normal async function, so you can call it directly and assert on its output — billing is applied transparently around it, so your core logic is fully testable in isolation.

Cover the cases that matter: valid input, invalid input, and upstream failures. Use whatever test runner your project already uses and run it with npm test — the project scaffolded by create-settlegrid-tool ships with a test setup ready to go.

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 from your SettleGrid dashboard (Dashboard → Tools → New Tool), or programmatically with PUT /api/tools/publish using your API key. Publishing validates your configuration, runs the listing quality checks, and creates your tool listing. 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 — copy the markdown from your tool listing page, e.g. [![SettleGrid](https://settlegrid.ai/api/badge/tool/your-slug)](https://settlegrid.ai/tools/your-slug). The badge 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.