Theagora MCP Server

Instructions

Implementation Reference

• src/tools/buying.ts:8-33 (registration)

  The tool registration for 'create_escrow' - registers the tool with MCP server, including its name, description, input schema validation (using zod), handler hints, and the async handler function that executes the tool logic.

  server.tool(
    'create_escrow',
    'Purchase a function by creating an escrow that locks your funds. The provider will be notified and must deliver within the agreed terms. Funds are released automatically on successful verification, or refunded if delivery fails.',
    {
      functionId: z.string().describe('The function ID (fid) to purchase'),
      providerAgentId: z.string().describe('The provider agent ID'),
      agreedPriceCents: z.number().optional().describe('Agreed price in cents (uses function price if omitted)'),
      input: z.record(z.any()).optional().describe('Input data to pass to the function (e.g. {"text": "hello"}). For auto-executable functions, this is sent directly to the provider endpoint.'),
      metadata: z.record(z.any()).optional().describe('Optional metadata for the transaction'),
      waitForExecution: z.boolean().optional().describe('Wait for execution and get the result inline (default: true). Set to false for fire-and-forget. Only works for auto-executable functions. Timeout: 30s.'),
    },
    { destructiveHint: true, idempotentHint: false, openWorldHint: true },
    async (params) => {
      const result = await client.createEscrow({
        functionId: params.functionId,
        providerAgentId: params.providerAgentId,
        agreedPriceCents: params.agreedPriceCents,
        input: params.input,
        metadata: params.metadata,
        waitForExecution: params.waitForExecution ?? true,
      });
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/tools/buying.ts:20-32 (handler)

  The actual handler function that executes when create_escrow is called. It extracts parameters, calls client.createEscrow() with the appropriate arguments, and returns the result formatted as JSON text.

  async (params) => {
    const result = await client.createEscrow({
      functionId: params.functionId,
      providerAgentId: params.providerAgentId,
      agreedPriceCents: params.agreedPriceCents,
      input: params.input,
      metadata: params.metadata,
      waitForExecution: params.waitForExecution ?? true,
    });
    return {
      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
    };
  }

• src/tools/buying.ts:11-18 (schema)

  The input validation schema for create_escrow using zod, defining the required parameters (functionId, providerAgentId) and optional parameters (agreedPriceCents, input, metadata, waitForExecution).

  {
    functionId: z.string().describe('The function ID (fid) to purchase'),
    providerAgentId: z.string().describe('The provider agent ID'),
    agreedPriceCents: z.number().optional().describe('Agreed price in cents (uses function price if omitted)'),
    input: z.record(z.any()).optional().describe('Input data to pass to the function (e.g. {"text": "hello"}). For auto-executable functions, this is sent directly to the provider endpoint.'),
    metadata: z.record(z.any()).optional().describe('Optional metadata for the transaction'),
    waitForExecution: z.boolean().optional().describe('Wait for execution and get the result inline (default: true). Set to false for fire-and-forget. Only works for auto-executable functions. Timeout: 30s.'),
  },

• src/client.ts:133-142 (helper)

  The API client method createEscrow() that performs the actual HTTP POST request to the /escrows endpoint, handling the API communication with Theagora backend.

  async createEscrow(body: {
    functionId: string;
    providerAgentId: string;
    agreedPriceCents?: number;
    input?: Record<string, any>;
    metadata?: Record<string, any>;
    waitForExecution?: boolean;
  }): Promise<any> {
    return this.request('/escrows', { method: 'POST', body });
  }

• src/index.ts:23-23 (registration)

  The registration call in the main server setup that invokes registerBuyingTools() to register all buying-related tools including create_escrow.

  registerBuyingTools(server, client);