MCP Server

The workspace-scoped Model Context Protocol server built into the Platform API - world-model read tools for MCP clients and partner agents.

The Platform API hosts a Model Context Protocol server at /v1/mcp. It exposes your workspace's world-model data as MCP tools that any MCP-compatible client (Claude Code, partner agents, your own tooling) can call.

This is not Data-MCP. The Data Access (MCP) page documents a separate standalone service that authenticates with Classic API credentials. The /v1/mcp endpoint described here is the MCP surface built into the Platform API. Platform functions remain the path for agent-side data access; this endpoint is for external MCP clients.

Scope: workspace, not per-user

The MCP server is workspace-scoped. Every credential is bound to exactly one workspace, and a call sees that entire workspace's data - it is not scoped to an individual end user. If you need per-user (e.g. per-clinician) tool and data scoping, that is a different mechanism: see External Principals, which runs through the agent session, not this endpoint.

Authentication

Every request carries two things:

Header	Value
Authorization	Bearer <token> - either an identity-issued JWT or a workspace API key
X-Workspace-Id	the workspace UUID the call operates in

The workspace in the header is cross-checked against the credential's own workspace. A token for workspace A presented with X-Workspace-Id: B is rejected with 403 - a credential can never reach another tenant's data. A missing or malformed header is a 400; a missing/invalid/expired token is 401.

Requests are rate-limited per (workspace, credential) on a sliding window of 120 requests per 60 seconds. A client that exceeds the limit receives 429 with a Retry-After header (seconds to wait) plus X-RateLimit-Limit, X-RateLimit-Remaining (always 0 on a 429), and X-RateLimit-Reset (Unix timestamp when the window resets). The limit fails open: if the rate-limiting infrastructure is temporarily unavailable, requests are allowed through.

Claude Code example

The server is mounted at /v1/mcp; the streamable-HTTP transport endpoint that clients connect to lives at /v1/mcp/mcp under that mount, which is why the URL below has the doubled segment.

{
  "mcpServers": {
    "amigo-world": {
      "type": "http",
      "url": "https://api.platform.amigo.ai/v1/mcp/mcp",
      "headers": {
        "Authorization": "Bearer ak_...",
        "X-Workspace-Id": "2c768c50-..."
      }
    }
  }
}

Tools

Read tools are available to every workspace credential except the two raw data-access tools (sql_query and call_function), which require the Data:Query permission (admin role). Every tool call is scoped to the header workspace, and PHI-bearing reads are HIPAA-audited.

Tool	Purpose
describe_schema	List the queryable tables, catalogs, and callable functions
list_entities	List workspace entities (filterable by type/name)
get_entity	Full detail for one entity
entity_timeline	Event history for an entity
entity_graph	An entity's relationships and neighbors
search_semantic	Semantic entity search (find entities by meaning, not exact match)
get_metrics	Workspace-aggregate metrics
query_analytics	Call analytics (quality, duration, trends)
list_platform_functions	Discover the workspace's registered platform functions
invoke_platform_function	Invoke a registered platform function with typed arguments
sql_query	Ad-hoc read-only SQL over the workspace data surface - admin only (Data:Query)
call_function	Invoke a warehouse function by name - admin only (Data:Query)

sql_query accepts only read-only statements over the documented, workspace-scoped tables, and every multi-tenant table in a query must be scoped by workspace_id = :ws_id (each table by its own alias - a join that scopes only one side is rejected). call_function carries the same Data:Query gate and is limited to an allow-list of platform-defined world functions.

Partner/world-tools surface (opt-in)

Where enabled, the server can additionally register:

• the world-tools read surface (list_world_read_tools, world_read, list_workspace_data_queries, invoke_workspace_data_query) - the agent's typed world-model reads and your workspace's registered read-only queries, re-exported to external/partner agents;
• world-model write tools and surface tools - entity-anchored and idempotent (every write takes an idempotency_key).

These are disabled by default and not generally available; they are enabled only for explicitly onboarded deployments.

Related

• External Principals - per-user (e.g. per-clinician) role-scoped tool access through the agent session.
• Workspace Data Queries - the registered read-only queries exposed via invoke_workspace_data_query.
• Platform Functions - agent-side data access (a different surface from this endpoint).
• Data Access (MCP) - the separate standalone Data-MCP service (Classic API credentials).