Add Sales Tax to an MCP Tool
If you run a paid MCP server, the quote your tool returns should carry the tax line before anyone is charged. Here is a working TypeScript MCP tool that does that, plus the in-memory test we ran against production.
Published November 18, 2026. The code on this page was tested against the production API on November 18, 2026; the testing section says exactly what ran.
Two different jobs
You want an assistant to calculate tax. Connect the published AgentTax MCP server and you are done: npx -y @agenttax/mcp-server exposes 15 tools, from calculate_tax to nexus and capital gains lookups. The MCP integration page has the client configuration.
You sell something through your own MCP server and each paid call needs a price with tax on it. That is this guide: your tool calls the AgentTax API itself and returns one quote with the price, the tax and the total.
npm install @modelcontextprotocol/sdk agenttax zodThe tool
quote_with_tax takes the price and the buyer's location, asks AgentTax for the seller-side figure, and returns a small JSON quote. It uses the official MCP TypeScript SDK and the agenttax npm client.
// npm install @modelcontextprotocol/sdk agenttax zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { AgentTaxClient } from "agenttax";
import { z } from "zod";
// No key = keyless demo mode (10 calculate calls a day per IP).
const tax = new AgentTaxClient({ apiKey: process.env.AGENTTAX_API_KEY });
export const server = new McpServer({ name: "my-paid-tool", version: "1.0.0" });
server.registerTool(
"quote_with_tax",
{
description: "Quote a paid call: price, US sales tax and total. Call before charging.",
inputSchema: {
price_usd: z.number().positive(),
buyer_state: z.string().length(2),
buyer_zip: z.string().regex(/^\d{5}$/).optional(),
customer_id: z.string().min(1),
},
},
async ({ price_usd, buyer_state, buyer_zip, customer_id }) => {
try {
const r = await tax.calculate({
role: "seller",
amount: price_usd,
buyerState: buyer_state,
buyerZip: buyer_zip,
transactionType: "api_access",
counterpartyId: customer_id,
intent: "estimate",
});
const quote = {
price_usd,
tax_usd: r.total_tax,
total_usd: Math.round((price_usd + r.total_tax) * 100) / 100,
confidence: r.confidence?.level,
agenttax_transaction_id: r.transaction_id,
};
return { content: [{ type: "text", text: JSON.stringify(quote) }] };
} catch (err) {
// Tell the calling model what went wrong instead of failing the session.
return { isError: true, content: [{ type: "text", text: `Tax quote failed: ${err.message}` }] };
}
},
);role: "seller"because your server is the seller. Seller-side figures for most states stay at 0 until you register your states withPOST /api/v1/nexus(or theconfigure_nexustool on the AgentTax MCP server), and the response says when that is the reason: readresolution.nexusand the advisories, not the total alone. Keyless calls run on a shared demo nexus profile, andresolution.nexussays so, so expect a different figure once you add a key and register your own states.intent: "estimate"keeps the quote out of your transaction history. When the charge actually settles, call again withintent: "record"(the default for keyed calls) so the sale counts toward nexus monitoring.- Failures return
isError: truewith a readable message, which MCP clients pass to the model instead of ending the session.
Run it over stdio
The server module has no transport of its own, which keeps it testable. To run it for a real client, connect it to stdio and point any MCP client that launches local servers at node main.mjs, with AGENTTAX_API_KEY in its environment.
// Run as a stdio MCP server: node main.mjs
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { server } from "./server.mjs";
await server.connect(new StdioServerTransport());Test it without a client
The MCP SDK ships an in-memory transport, so a test can connect a real client to the server in the same process, list the tools and call one. This is the exact script we ran on 18 November 2026 against production with no API key. It made one calculate call and every field came back.
// Smoke test for the /guides/mcp-server-sales-tax snippets.
// Connects an MCP client to server.mjs in memory, lists tools, and calls
// quote_with_tax once against production with no API key (1 keyless call).
import assert from "node:assert";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { server } from "./server.mjs";
const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
await server.connect(serverSide);
const client = new Client({ name: "smoke-test", version: "0.0.1" });
await client.connect(clientSide);
const { tools } = await client.listTools();
assert.deepStrictEqual(tools.map((t) => t.name), ["quote_with_tax"]);
const res = await client.callTool({
name: "quote_with_tax",
arguments: { price_usd: 49, buyer_state: "NY", buyer_zip: "10001", customer_id: "cust-123" },
});
assert.ok(!res.isError, res.content?.[0]?.text);
const quote = JSON.parse(res.content[0].text);
for (const k of ["price_usd", "tax_usd", "total_usd", "confidence", "agenttax_transaction_id"]) {
assert.ok(k in quote, `missing ${k}`);
}
assert.strictEqual(typeof quote.tax_usd, "number");
console.log("ok", Object.keys(quote).join(","));
await client.close();Before you go live
- Pass a ZIP when you have one. Without it the API uses the state rate only, and
resolution.locationsays so (basisstate_only). - Use a stable
customer_id. It is the counterparty the API records against, and it is how your history lines up with your billing system. - Keyless calls stop at 10 a day. A free key covers 1,500 calls a month; agents that would rather not hold a key can pay per call over x402.
AgentTax returns calculations for information; they are not tax advice. See the disclaimer. More guides: all developer guides.
Run it against your own transactions
10 keyless calls a day to try it. A free key gives 1,500 calls a month with the full response, no card.