Your own MCP server for AI agents

The published server, in one line

npx -y https://swapzilla.io/mcp/swapzilla-mcp-1.0.0.tgz

Register it with any MCP client — Claude Desktop, Claude Code, Cursor, Windsurf — and the agent gets six tools:

Two environment variables configure it: SWAPZILLA_API_BASE (defaults to https://api.swapzilla.io) and an optional SWAPZILLA_API_KEY, which it sends as X-API-Key. Public rate data needs neither. Install instructions, the client config block and the package itself are on /mcp/.

When to host your own instead

The published server is deliberately plain: it is the aggregator, exposed as tools, for whoever is running the agent. A partner integration usually wants things it does not have — and every one of them is a reason to wrap the partner API yourself.

Your own server, in about fifty lines

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const BASE = "https://api.swapzilla.io";
const KEY = process.env.SWAPZILLA_KEY!;              // stays in this process
const server = new McpServer({ name: "acme-swaps", version: "1.0.0" });

server.tool(
  "quote_swap",
  {
    from_asset: z.string(), from_network: z.string(),
    to_asset: z.string(), to_network: z.string(),
    amount_from: z.string().optional(), amount_to: z.string().optional(),
    rate_type: z.enum(["floating", "fixed"]).default("floating"),
  },
  async (args) => {
    const r = await fetch(`${BASE}/v1/partner/quotes?${new URLSearchParams(args)}`, {
      headers: { "X-API-Key": KEY },
    });
    const { offers } = await r.json();
    // Hand back only what a model should reason about, not the whole payload.
    return { content: [{ type: "text", text: JSON.stringify(offers.slice(0, 5).map((o) => ({
      id: o.ID, provider: o.ProviderName, receive: o.ToAmount,
      minutes: o.EstimatedMins, kyc: o.KycRating, worse_by_percent: o.DeviationPercent,
    }))) }] };
  },
);

await server.connect(new StdioServerTransport());

The writing tool is the same shape with the guardrails wrapped around it:

server.tool(
  "create_swap",
  { offer_id: z.string(), to_address: z.string(), intent_id: z.string() },
  async ({ offer_id, to_address, intent_id }) => {
    assertAllowed(to_address);                       // your allow-list
    await requireApproval(intent_id);                // your human, or your policy

    const r = await fetch(`${BASE}/v1/partner/orders`, {
      method: "POST",
      headers: {
        "X-API-Key": KEY, "Content-Type": "application/json",
        "Idempotency-Key": intent_id,                // one intent, one order
      },
      body: JSON.stringify({
        offer_id, to_address,
        refund_address: process.env.TREASURY_ADDRESS,
        client_order_id: intent_id,
      }),
    });
    const order = await r.json();
    return { content: [{ type: "text", text:
      `Send exactly ${order.AmountFrom} ${order.FromAsset} on ${order.FromNetwork} ` +
      `to ${order.DepositAddress}. Order ${order.ID}.` }] };
  },
);

The read-only tools — assets, quotes, address validation, status — are safe to let an agent call freely. Only the one that creates an order needs a gate in front of it.

Guardrails worth having

• Allow-list the destination. Restrict to_address to addresses your system already knows, and reject the rest inside the tool.
• Cap the amounts. Per intent and per day, checked in the server. A model's judgement is not a spending limit.
• One intent, one idempotency key. Agents retry; the key is what keeps a retry from becoming a second swap.
• Quote and confirm inside five minutes. Offers expire, so a plan approved twenty minutes later must be re-quoted — and the tool should say so rather than silently repricing.
• Never put the key in the model's context. It lives in the server process, is never returned by a tool and never rendered into a prompt.
• Log ProviderOrderID. It is the reference the provider's support recognises when a swap needs chasing.

What neither server can do

Questions