MCP Protocol

Fp Switchboard implements the Model Context Protocol (MCP), an open standard for connecting AI assistants to external tools and data sources.

What is MCP?

MCP is a JSON-RPC 2.0 based protocol that allows AI models to:

Discover tools available in a system
Execute tools with specific parameters
Receive results in a standardized format

Protocol Basics

JSON-RPC 2.0

All MCP messages follow JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": {}
}

Transport

Fp Switchboard uses HTTP transport:

Endpoint: https://api.switchboard.fpdigital.ai/mcp/{service}
Method: POST
Headers: Authorization: Bearer {token}

Core Methods

tools/list

Returns available tools for the authenticated token:

Request
Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "gmail_search",
        "description": "[Gmail] Search emails with query",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Gmail search query"
            },
            "max_results": {
              "type": "integer",
              "default": 10
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

tools/call

Executes a tool with the provided arguments:

Request
Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "gmail_search",
    "arguments": {
      "query": "from:boss@company.com",
      "max_results": 5
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 emails:\n\n1. Subject: Q4 Planning..."
      }
    ]
  }
}

Tool Schema

Each tool has an inputSchema following JSON Schema:

{
  "name": "calendar_create",
  "description": "[Calendar] Create a new calendar event",
  "inputSchema": {
    "type": "object",
    "properties": {
      "summary": {
        "type": "string",
        "description": "Event title"
      },
      "start": {
        "type": "string",
        "description": "Start time (ISO 8601)"
      },
      "end": {
        "type": "string",
        "description": "End time (ISO 8601)"
      },
      "attendees": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Email addresses of attendees"
      },
      "account": {
        "type": "string",
        "description": "Account alias (required if multiple accounts)"
      }
    },
    "required": ["summary", "start", "end"]
  }
}

Response Format

Success Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Operation completed successfully"
      }
    ]
  }
}

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Service not connected",
    "data": {
      "service": "google",
      "errorCode": "SERVICE_NOT_CONNECTED"
    }
  }
}

Error Codes

Code	Meaning
-32700	Parse error (invalid JSON)
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32000	Service error (see data.errorCode)

Service Error Codes

errorCode	Meaning
`AUTH_FAILED`	Token invalid or expired
`SERVICE_NOT_CONNECTED`	Service not connected
`RATE_LIMITED`	Too many requests
`INVALID_INPUT`	Invalid tool parameters
`NOT_FOUND`	Resource not found
`SERVICE_ERROR`	Upstream service error

Batch Requests

MCP supports batch requests:

[
  { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "gmail_search", "arguments": { "query": "is:unread" } } },
  { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "calendar_list", "arguments": {} } }
]

Rate Limiting

Endpoint	Limit
`/mcp/unified`	100 req/min
`/mcp/{service}`	60 req/min
`tools/list`	10 req/min

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Multi-Account Handling

For users with multiple accounts connected, tools include an account parameter:

{
  "name": "gmail_send",
  "inputSchema": {
    "properties": {
      "account": {
        "type": "string",
        "description": "Account alias: work, personal"
      }
    }
  }
}

See Multi-Account Access for details.