# MCP server

OhAuthCat hosts a Model Context Protocol server at `https://mcp.ohauthcat.com/mcp`. It lets a coding assistant look up your organizations and connections, explain an error code, read a sign-in timeline and create a portal link, using a key you scope tightly.

## Tools

| Tool                   | Scope it needs        | What it does                                                 |
| ---------------------- | --------------------- | ------------------------------------------------------------ |
| `list_organizations`   | `organizations:read`  | Lists organizations in the environment                       |
| `list_connections`     | `connections:read`    | Lists connections                                            |
| `get_connection`       | `connections:read`    | Reads one connection without credentials or raw certificates |
| `get_sign_in_timeline` | `workbench:read`      | Reads the steps of one sign-in                               |
| `explain_error`        | none beyond `mcp:use` | Explains a catalogue error code or one of your request IDs   |
| `search_docs`          | none beyond `mcp:use` | Searches these docs                                          |
| `create_portal_link`   | `portal_links:write`  | Creates a hosted portal link; needs an idempotency key       |

`create_portal_link` is the only tool that changes configuration.

## Create the key

Create a restricted secret key with `mcp:use` plus only the tool scopes you want. A key with `*`, or with any scope outside `mcp:use`, `organizations:read`, `connections:read`, `workbench:read` and `portal_links:write`, is refused with [`mcp_key_too_broad`](/errors/mcp_key_too_broad/). A leaked agent key therefore cannot write broadly through the management API.

Put the key in your assistant's MCP configuration as a bearer token. Never commit it.

## Protocol details

- Streamable HTTP, stateless: one JSON-RPC 2.0 message per POST, JSON responses, no batches and no server-sent events. GET returns 405.
- Protocol versions `2025-06-18` and `2025-11-25`. After `initialize`, send the negotiated version in the `MCP-Protocol-Version` header.
- Requests are capped at 256 KiB and each tool result at 64 KiB.
- Each key gets 60 tool calls per rolling minute.
- Browser clients must send an allowed `Origin` or none at all; otherwise the server answers 403 with [`mcp_origin_refused`](/errors/mcp_origin_refused/).
- Revoking a key or changing its scopes takes effect within the configuration refresh window, not instantly.

## Untrusted text

Names your customers type, such as organization and connection names and custom attribute keys, appear only inside an `untrusted` object in tool results. Your assistant must treat that text as data, never as instructions. Every tool description says so.

Every tool call is audited with the key, the tool name and identifiers. Submitted names, queries and other values are not stored.
