> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/functions/mcp-server.md).
# MCP Server
The Platform API hosts a [Model Context Protocol](https://modelcontextprotocol.io) 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.
{% hint style="info" %}
**This is not Data-MCP.** The [Data Access (MCP)](/developer-guide/platform-api/data-world-model/data-mcp.md) 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*.
{% endhint %}
## 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](/developer-guide/platform-api/integrations/external-principals.md), which runs through the agent session, not this endpoint.
```mermaid
flowchart LR
subgraph MCP["/v1/mcp - workspace grain"]
cred["One credential
(API key or JWT)"] --> all[("Entire workspace's
world-model data")]
end
subgraph EP["External Principals - per-user grain"]
user["End-user session
(anchored to an entity)"] --> gate{"Role grants"} --> slice[("Only the tools & data
the user's roles allow")]
end
```
## Authentication
Every request carries two things:
| Header | Value |
| ---------------- | ----------------------------------------------------------------------- |
| `Authorization` | `Bearer ` - 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.
```mermaid
flowchart TD
C["MCP client
Authorization + X-Workspace-Id"] --> V{"Verify token"}
V -->|missing / invalid / expired| E401["401"]
V -->|"token workspace ≠ header"| E403["403"]
V -->|verified| RL{"Under rate limit?"}
RL -->|no| E429["429 + Retry-After"]
RL -->|yes| B["Bind to workspace"]
B --> T["Tool dispatch
(scoped to this workspace)"]
T --> D[("World-model data")]
T -. "PHI read" .-> A["HIPAA audit"]
```
### 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.
```json
{
"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 |
| `get_metrics` | Workspace-aggregate metrics |
| `query_analytics` | Call analytics (quality, duration, trends) |
| `list_platform_functions` | Discover the workspace's registered [platform functions](/developer-guide/platform-api/functions.md) |
| `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 writes that require an `idempotency_key`. Successful results are deduplicated for one hour for the same workspace, identity anchor, tool, and key. Deduplication can fail open if that control is unavailable or its bounded wait expires, so this reduces duplicate retries but is not a transactional exactly-once guarantee.
These are **disabled by default** and not generally available; they are enabled only for explicitly onboarded deployments.
## Related
* [External Principals](/developer-guide/platform-api/integrations/external-principals.md) - per-user (e.g. per-clinician) role-scoped tool access through the agent session.
* [Workspace Data Queries](/developer-guide/platform-api/functions/workspace-data-queries.md) - the registered read-only queries exposed via `invoke_workspace_data_query`.
* [Platform Functions](/developer-guide/platform-api/functions.md) - agent-side data access (a different surface from this endpoint).
* [Data Access (MCP)](/developer-guide/platform-api/data-world-model/data-mcp.md) - the separate standalone Data-MCP service (Classic API credentials).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.amigo.ai/developer-guide/platform-api/functions/mcp-server.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.