Свой MCP-сервер для ИИ-агентов

Опубликованный сервер, одной строкой

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

Зарегистрируйте его в любом MCP-клиенте — Claude Desktop, Claude Code, Cursor, Windsurf — и у агента появятся шесть инструментов:

Настраивается двумя переменными окружения: SWAPZILLA_API_BASE (по умолчанию https://api.swapzilla.io) и необязательным SWAPZILLA_API_KEY, который отправляется как X-API-Key. Для публичных данных о курсах не нужен ни один из них. Инструкции по установке, блок конфигурации клиента и сам пакет — на /ru/mcp/.

Когда нужен свой сервер

Опубликованный сервер намеренно простой: это агрегатор, выставленный инструментами, для того, кто запускает агента. Партнёрской интеграции обычно нужно то, чего в нём нет, — и каждый такой пункт — повод обернуть partner API самостоятельно.

Свой сервер примерно на пятьдесят строк

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!;              // остаётся в этом процессе
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();
    // Возвращайте только то, о чём модель должна рассуждать, а не весь ответ.
    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());

Пишущий инструмент устроен так же — с ограничениями вокруг него:

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);                       // ваш белый список
    await requireApproval(intent_id);                // ваш человек или ваша политика

    const r = await fetch(`${BASE}/v1/partner/orders`, {
      method: "POST",
      headers: {
        "X-API-Key": KEY, "Content-Type": "application/json",
        "Idempotency-Key": intent_id,                // одно намерение — один ордер
      },
      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:
      `Отправьте ровно ${order.AmountFrom} ${order.FromAsset} в сети ${order.FromNetwork} ` +
      `на ${order.DepositAddress}. Ордер ${order.ID}.` }] };
  },
);

Читающие инструменты — активы, котировки, проверка адреса, статус — можно спокойно давать агенту. Ворота нужны только тому, который создаёт ордер.

Ограничения, которые стоит поставить

• Белый список адресов получения. Ограничьте to_address адресами, которые ваша система уже знает, и отклоняйте остальные внутри инструмента.
• Лимиты сумм. На намерение и на день, проверяются в сервере. Здравый смысл модели — не лимит расходов.
• Одно намерение — один idempotency-ключ. Агенты повторяют вызовы; ключ и не даёт повтору стать вторым обменом.
• Котировка и подтверждение внутри пяти минут. Предложения истекают, поэтому план, одобренный через двадцать минут, нужно пересчитать — и инструмент должен об этом сказать, а не молча переоценить.
• Никогда не помещайте ключ в контекст модели. Он живёт в процессе сервера, не возвращается инструментами и не попадает в промпт.
• Логируйте ProviderOrderID. Это та ссылка, которую понимает поддержка провайдера, если обмен приходится «догонять».

Чего не может ни один из серверов

Вопросы