MCP Tools API Reference

The MCP Tools Server exposes tools to ADK agents and external MCP clients through a REST API and a streamable HTTP MCP endpoint. For architecture and configuration, see MCP Tools Server.

Paths are relative to the MCP service root (port 8102 locally; the container listens on MCP_BIND_PORT, default 8000). Authentication, required headers, and errors follow the API conventions. REST tool routes require X-Org-Id and return 400 without it.

Endpoints

There is no /ping/ route.

Health

GET /health/ returns {"status": "ok", "dependencies": {...}}, where dependencies lists runtime package versions.

List Tools

GET /tools/list/

curl -s 'http://localhost:8102/tools/list/' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Org-Id: YOUR_ORG_ID'

{
  "tools": [
    {
      "name": "acme_corp-api-weather_lookup-1_0",
      "description": "Current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  ]
}

Returns 503 with {"error": "MCP list_tools failed: ..."} when the listing fails.

Call Tool

POST /tools/call/

curl -s -X POST 'http://localhost:8102/tools/call/' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Org-Id: YOUR_ORG_ID' \
  -H 'Content-Type: application/json' \
  -d '{"tool_name": "acme_corp-api-weather_lookup-1_0", "args": {"city": "London"}}'

{
  "content": [{"type": "text", "text": "..."}],
  "meta": null,
  "isError": false,
  "structured_content": {},
  "data": {}
}

structured_content and data appear only when the tool returns them. Failures use the same shape with isError: true and an error_type in meta:

Auto-sync

If a tool is missing from the in-memory registry and Redis, AutoSyncMiddleware fetches it from Configurator (/api/v1/tools/mcp-list/), stores it in Redis DB 11, registers it, and continues the call. TOOL_AUTO_SYNC_ENABLED and TOOL_AUTO_SYNC_TIMEOUT control this behavior.

MCP Protocol

POST /mcp serves the streamable HTTP transport from the MCP specification for ADK MCPToolset, Claude Desktop, and other MCP clients. Authenticate with Authorization: Bearer <token> or an access_token cookie. External clients can obtain a token through the OAuth2 routes when MCP_OAUTH_ENABLED is on.

ADK's service client must send X-Org-Id plus X-On-Behalf-Of-User-Id or X-Subject-User-Id; otherwise the request returns 403.

Request headers

Tool search

The tool list is reduced to search_tools (BM25 search, up to 8 results) and call_tool, plus always-visible tools: get_current_user, cosmos_list_organizations, cosmos_list_files, cosmos_upload_file, cosmos_get_direct_endpoints, and cosmos_get_bearer_token.

OAuth2 routes

Enabled when MCP_OAUTH_ENABLED=true: GET /.well-known/oauth-protected-resource, GET /.well-known/oauth-authorization-server, POST /register, GET /authorize, the login callback, and POST /token. MCP proxies the User Service login and passes its JWT through.

Tool Names

Configurator assigns every tool configuration an mcp_tool_name of the form {org}-{type}-{name}-{major}_{minor}, for example acme_corp-api-weather_lookup-1_0. Use that name in tool_name and in X-MCP-Tools.

Caching

The tools-consumer process reads Configurator events from the configurator Kafka topic and updates Redis. Auto-sync fills cache misses on demand.