Adding Custom MCP Tools

Overview

MCP (Model Context Protocol) tools let the AI call your backend services. Each tool has:

A definition (name, description, input schema) — shown to the AI
A handler in executeTool() — routes the call to your backend

Step-by-Step

1. Add your backend URL

In mcp-bridge/index.js, add your service to CLOUD_FUNCTIONS:

javascript

const CLOUD_FUNCTIONS = {
  myService: process.env.MY_SERVICE_URL || "https://my-service-abc123.run.app",
};

2. Define the tool

Add a tool object to the TOOLS array:

javascript

{
  name: "lookup_customer",
  description: "Look up a customer by ID or name. Returns profile, account status, and recent activity.",
  inputSchema: {
    type: "object",
    properties: {
      customerId: { type: "string", description: "Customer ID (e.g., 'CUST-1234')" },
      name: { type: "string", description: "Customer name to search" },
    },
    required: [],  // neither is required — the AI can provide either
  },
}

Tips for good tool descriptions:

Be specific about what it does and what it returns
Include example values in property descriptions
The AI uses descriptions to decide when to call the tool

3. Add the handler

In executeTool(), add a case for your tool:

javascript

case "lookup_customer":
  return callCloudFunction(CLOUD_FUNCTIONS.myService, {
    action: "get_customer",
    customerId: args.customerId,
    name: args.name,
  });

4. Update the system prompt

In config/config.json, add the tool to systemPrompt so the AI knows when to use it:

3. **lookup_customer** — Look up customer profiles and account details.
   USE FOR: "who is customer X?", "find customer", any question mentioning a customer ID.

Supported Input Types

JSON Schema Type	Example
`string`	`{ type: "string" }`
`number`	`{ type: "number" }`
`boolean`	`{ type: "boolean" }`
`array`	`{ type: "array", items: { type: "string" } }`
`object`	`{ type: "object" }`
`enum`	`{ type: "string", enum: ["a", "b", "c"] }`

Backend Response Format

Your Cloud Function should return JSON. The MCP bridge wraps it in the MCP response format automatically.

javascript

// Your backend returns:
{ "customer": { "id": "CUST-1234", "name": "Jane Doe", "status": "active" } }

// MCP bridge wraps it as:
{
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "{\"customer\":{...}}" }]
  }
}

Multiple Actions per Tool

A single tool can support multiple actions:

javascript

// Tool definition with enum actions
{
  name: "manage_orders",
  description: "Manage orders: list, search, create, or update.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string", enum: ["list", "search", "create", "update"] },
      orderId: { type: "string" },
      query: { type: "string" },
      data: { type: "object" },
    },
    required: ["action"],
  },
}

// Handler routes based on action
case "manage_orders": {
  const payload = { action: args.action };
  if (args.action === "search") payload.query = args.query;
  if (args.action === "create") payload.data = args.data;
  if (args.orderId) payload.orderId = args.orderId;
  return callCloudFunction(CLOUD_FUNCTIONS.orders, payload);
}

Testing Tools

bash

# List all registered tools
curl -s -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

# Call a specific tool
curl -s -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,"method":"tools/call",
    "params":{"name":"lookup_customer","arguments":{"customerId":"CUST-1234"}}
  }' | jq '.result.content[0].text' -r | jq .