MCP Tools Server

The MCP Tools Server (cosmos-mcp-v3) is the tool execution layer of the Cosmos platform. Built on FastMCP, it exposes tools over HTTP REST and the MCP protocol to two audiences: internal clients (ADK, JumpStart apps) get organization-specific API, DB, custom, and connector tools, and external AI assistants (Claude Desktop, Factory) get Cosmos platform management tools (cosmos_*) over MCP with OAuth2.

Why It Matters

MCP is where a tool call actually executes. Configurator owns tool definitions and ADK decides which tools an agent needs; MCP runs the HTTP call, database query, or connector invocation, and caps response size so a large tool output cannot overflow an agent's context window.

Architecture At A Glance

Tool providers:

HTTP authentication: MCPAuthMiddleware (ASGI) protects the MCP transport path (MCP_PATH, default /mcp). It accepts a bearer token or an access_token cookie and caches session authorization. ADK's service client (cosmos-adk-v3) must send X-Org-Id and a delegated user (X-On-Behalf-Of-User-Id or X-Subject-User-Id), or the request is rejected with 403. Other callers must hold mcp.tool.call or mcp.tool.list. REST routes check permissions per route.

FastMCP middleware, in order: AutoSyncMiddleware (fetches tools missing from the cache from Configurator), ResilientPingMiddleware (15-second keep-alive), and ResponseLimitingMiddleware (caps tool output at 500 KB).

Tool search: a BM25 search transform replaces the full catalog with two synthetic tools, search_tools (up to 8 results) and call_tool. The pinned tools and get_current_user stay visible without searching.

Key Capabilities

• Two-level auto-sync — a tool missing from cache is fetched from Configurator and synced to Redis, either per call (/tools/call/) or in batch when ADK's X-MCP-Tools header lists an agent's tools.
• Tool visibility — requests without X-Org-Id (external assistants) see the cosmos_* tools, get_current_user, and the search tools. Requests with X-Org-Id see the organization's tools without cosmos_*, unless X-Cosmos-Platform-Assistant is true; platform write tools then also need X-Cosmos-Platform-Write-Confirmed.
• Connector tools — external MCP servers configured per organization. Each discovered tool is tagged with its org_id and connector for scoped filtering.
• Inbuilt tools — get_current_user, knowledge_base, web_browse, and the DMS family: dms_read_file, dms_write_file, dms_delete_file, dms_list_files, dms_search_files, dms_file_exists, dms_move_file, dms_get_file_url, and dms_merge_documents.
• Knowledge base authorization — when X-Project-Id is sent, knowledge_base authorizes each collection and graph against the project (cosmos.kb.read), checks it against the agent's resource manifest, and forwards X-Project-Id to RAGflow.
• Cosmos platform tools — 63 cosmos_* tools covering tools, agents, apps, skills, templates, prompts, knowledge base, connectors, files, and guardrails. Agent tools accept pinned skill and sub-agent versions. Five are pinned regardless of search: cosmos_list_organizations, cosmos_list_files, cosmos_upload_file, cosmos_get_direct_endpoints, cosmos_get_bearer_token.
• OAuth2 proxy for external clients — when MCP_OAUTH_ENABLED is on, clients discover /.well-known/oauth-authorization-server, register, are redirected through /authorize to the User Service login, and exchange a code for a token at /token. MCP passes the User Service JWT through; it does not mint its own.

API Overview

→ Full API reference: MCP API

Configuration

MCP runs on Python 3.12–3.13 and uses uv for dependencies (uv sync, uv run server.py). Key dependencies: fastmcp==3.4.10, mcp==1.30.0, confluent-kafka, redis, httpx, database drivers, and connector SDKs. Telemetry uses azure-monitor-opentelemetry: the container entrypoint runs the server and the Kafka consumer under opentelemetry-instrument and maps APPINSIGHTSCONNECTIONSTRING to APPLICATIONINSIGHTS_CONNECTION_STRING.

Integration Points

Troubleshooting

• Tools not appearing after deployment — check the tools-consumer logs (./manage.sh dev logs tools-consumer), confirm the tool is deployed in Configurator, and restart with ./manage.sh dev restart tools-server.
• Auto-sync failures — search the tools-server logs for "Auto-sync"; verify CONFIGURATOR_SERVICE_URL, COSMOS_SERVICE_CLIENT_ID, and COSMOS_MCP_SERVICE_CLIENT_SECRET.
• OAuth2 not working — verify MCP_OAUTH_ENABLED=true and the OAuth client variables, confirm the User Service is reachable (curl http://localhost:8101/health/), and run ./manage.sh <env> setup-oauth to regenerate the OAuth application.

Changelog

See the MCP changelog for verified changes.