toreador_create_session

Instructions

Implementation Reference

• src/index.ts:56-85 (registration)

  The free-tier tool definitions array; toreador_create_session is NOT in this array because it requires a Pro key. This shows the registration location context.

  const FREE_TIER_TOOLS: Tool[] = [
    {
      name: "toreador_generate_qr",
      description:
        "Generate a crypto QR code for a native token (BTC, ETH, SOL, POL) or a Solana SPL token (USDC on Solana). Returns the QR data URI (PNG base64) and the on-chain payment URI (BIP21, EIP-681, Solana Pay). FREE — no API key needed for these chains. For ERC-20 stablecoins on Ethereum/Polygon/Base (USDT, USDC, EURC), use toreador_create_session (Pro plan required).",
      inputSchema: {
        type: "object",
        properties: {
          token: {
            type: "string",
            description: "Token symbol. One of: BTC, ETH, SOL, POL, USDC (Solana only).",
          },
          chainId: {
            type: "string",
            description: "Chain identifier. One of: bitcoin, ethereum, polygon, base, solana.",
          },
          amount: {
            type: "string",
            description: "Amount as a decimal string in the token's natural unit (e.g. \"0.001\" for BTC, \"50\" for USDC). Use a string to preserve decimal precision.",
          },
          recipientAddress: {
            type: "string",
            description: "Destination wallet address. Must match the chain (bech32 for BTC, EIP-55 for EVM, base58 for Solana).",
          },
        },
        required: ["token", "chainId", "amount", "recipientAddress"],
        additionalProperties: false,
      },
    },
  ];

• src/index.ts:90-117 (schema)

  Schema definition for toreador_create_session: name, description, and inputSchema with required fields: token (USDC/USDT/EURC), chainId (ethereum/polygon/base), amount, recipientAddress.

  {
    name: "toreador_create_session",
    description:
      "Create a hosted payment session for ERC-20 stablecoins on EVM chains (USDC, USDT, EURC on Ethereum, Polygon or Base). Returns a session ID, a 6-character security code to display to the payer, and a URL to a Toreador-hosted payment page where the payer connects their wallet. Sessions expire 15 minutes after creation. PRO PLAN REQUIRED. For native tokens or Solana SPL, use toreador_generate_qr instead.",
    inputSchema: {
      type: "object",
      properties: {
        token: {
          type: "string",
          description: "Stablecoin symbol. One of: USDC, USDT, EURC.",
        },
        chainId: {
          type: "string",
          description: "EVM chain. One of: ethereum, polygon, base.",
        },
        amount: {
          type: "string",
          description: "Amount in the token's natural unit (e.g. \"100\" for 100 USDC).",
        },
        recipientAddress: {
          type: "string",
          description: "Destination EVM wallet address (0x...).",
        },
      },
      required: ["token", "chainId", "amount", "recipientAddress"],
      additionalProperties: false,
    },
  },

• src/index.ts:212-218 (handler)

  Handler: the callTool switch dispatches 'toreador_create_session' to a POST /create-session request with token, chainId, amount, recipientAddress via the toreadorRequest helper.

  case "toreador_create_session":
    return toreadorRequest("POST", "/create-session", {
      token: args.token,
      chainId: args.chainId,
      amount: args.amount,
      recipientAddress: args.recipientAddress,
    });

• src/index.ts:158-191 (helper)

  toreadorRequest is the shared HTTP helper used by the handler. It constructs the URL, adds X-API-Key header, sets a timeout, and returns ok/status/data.

  async function toreadorRequest(
    method: "GET" | "POST",
    path: string,
    body?: unknown,
  ): Promise<{ ok: boolean; status: number; data: unknown }> {
    const url = `${TOREADOR_BASE_URL}${path}`;
    const headers: Record<string, string> = {
      "Accept": "application/json",
      "User-Agent": "toreador-mcp-server/0.2.0",
    };
    if (TOREADOR_API_KEY) headers["X-API-Key"] = TOREADOR_API_KEY;
    const init: RequestInit = { method, headers };
    if (body !== undefined) {
      headers["Content-Type"] = "application/json";
      init.body = JSON.stringify(body);
    }
  
    const ctrl = new AbortController();
    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
    init.signal = ctrl.signal;
  
    try {
      const res = await fetch(url, init);
      let data: unknown = null;
      try {
        data = await res.json();
      } catch {
        // non-JSON response — leave data as null
      }
      return { ok: res.ok, status: res.status, data };
    } finally {
      clearTimeout(timer);
    }
  }

• src/index.ts:290-320 (registration)

  The MCP CallToolRequestSchema handler that receives tool calls, checks Pro key guard for toreador_create_session, then calls callTool which dispatches to the handler.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const name = request.params.name;
    const args = (request.params.arguments || {}) as ToolArgs;
  
    // Guard: Pro-only tool but no API key configured. Tell the LLM how to fix.
    if (PRO_TOOL_NAMES.has(name) && !HAS_API_KEY) {
      return {
        isError: true,
        content: [{
          type: "text" as const,
          text: `Tool ${name} requires a Toreador Pro plan API key. Set the TOREADOR_API_KEY environment variable in your MCP client config (format: tdr_...). Get a key at https://toreador.io/dashboard#api (Pro plan required: https://toreador.io/go-pro). The free tools (toreador_generate_qr) remain available for native tokens (BTC, ETH, SOL, POL, USDC on Solana) without a key.`,
        }],
      };
    }
  
    try {
      const result = await callTool(name, args);
      return formatToolResult(name, result);
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      return {
        isError: true,
        content: [
          {
            type: "text" as const,
            text: `Tool ${name} failed: ${message}`,
          },
        ],
      };
    }
  });