# Connect via MCP

Drive your Polimorf workspace from an MCP client such as Claude, authenticated with OAuth 2.1 and scoped to your own role and organization.

Source: https://docs.polimorf.app/docs/mcp

Polimorf exposes its control plane over the **Model Context Protocol (MCP)**, so
an MCP client — Claude Desktop, the Claude web connectors, or your own agent —
can read and manage your assistants, environments, knowledge, deployments and
more, acting **as you**. Every call reuses the same role-based permissions as the
dashboard: an MCP session can never do anything your account could not.

Unlike the runtime API (which uses a workspace [API key](/docs/authentication)),
the control plane authenticates with **OAuth 2.1**. You approve a connection once
on a consent screen; the client receives short-lived tokens and you can revoke
the connection at any time.

## The MCP endpoint

| Environment       | MCP endpoint                   |
| ----------------- | ------------------------------ |
| Managed (default) | `https://api.polimorf.app/mcp` |
| Self-hosted       | `https://<your-host>/mcp`      |

The endpoint speaks Streamable-HTTP JSON-RPC. Authorization metadata is published
for automatic discovery (no manual client secret):

- `GET /.well-known/oauth-protected-resource` (RFC 9728)
- `GET /.well-known/oauth-authorization-server` (RFC 8414)
- `GET /.well-known/jwks.json` — the public keys that sign access tokens

## Connect Polimorf

Most MCP clients support adding a remote server by URL and will walk you through
the OAuth flow automatically.

### Claude (Desktop or web connectors)

Add a custom connector pointing at the MCP endpoint:

```json
{
  "mcpServers": {
    "polimorf": {
      "url": "https://api.polimorf.app/mcp"
    }
  }
}
```

When you enable the connector, Claude:

1. Discovers the authorization server from the endpoint's metadata.
2. Registers itself dynamically (RFC 7591) — no manual client id/secret.
3. Sends you to Polimorf's **consent screen**, where you sign in (if needed),
   pick which organization to grant access to, and approve the requested scopes.
4. Exchanges the authorization code (PKCE) for an access token and starts a
   session.

<Callout type="info">
  Access is **single-organization by default**. On the consent screen you choose
  exactly one organization to bind the connection to; the session can never be
  steered into another organization you belong to. Choosing "all organizations"
  is an explicit opt-in.
</Callout>

## Scopes

A connection carries one or more MCP scopes. They gate whole classes of tools,
and are intersected with your role's permissions — you need **both** the scope
and the underlying permission for a tool to run.

| Scope       | Grants                                                                                                                                                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp:read`  | Read organizations, assistants, versions, environments, knowledge, traces (default)                                                                                                                                        |
| `mcp:write` | Create/update assistants and their drafts; publish versions; create/update environments and knowledge; author evaluation datasets; publish, roll back and run evaluations; run the playground; execute deployed assistants |
| `mcp:admin` | Administer members, API keys and provider credentials                                                                                                                                                                      |

A freshly approved connection defaults to **read-only** (`mcp:read`). Destructive
tools are flagged to the client so it can confirm before running them.

<Callout type="warn">
  Organization owners can disable administration over MCP entirely. When that
  toggle is off, every `mcp:admin` tool is denied for the organization
  regardless of the caller's role.
</Callout>

## What you can do

Once connected, the client can list and call Polimorf tools. A sample of the
catalog:

- **Discovery** — `whoami`, `list_organizations`, `list_workspaces`
- **Assistants** — `list_assistants`, `get_assistant`, `create_assistant`,
  `update_assistant`, `archive_assistant`, `restore_assistant`
- **Draft editing** — `get_assistant_draft`, `update_assistant_draft` (edit the
  prompt blocks, prompt variables, model configuration and knowledge/tool
  bindings of the working draft)
- **Versions & deployments** — `list_assistant_versions`, `get_assistant_version`,
  `create_assistant_version` (publish the current draft), `list_deployments`,
  `publish_deployment`, `rollback_deployment`
- **Environments** — `list_environments`, `create_environment`,
  `update_environment`, `delete_environment`
- **Knowledge** — `list_knowledge_sources`, `list_knowledge_documents`,
  `search_knowledge` (semantic search over a base's content),
  `download_knowledge_document` (fetch a document's original content — text
  files come back as text, binary files base64-encoded),
  `create_knowledge_source`, `add_knowledge_text` (add an inline text/markdown
  document; binary files use the API/SDK upload), `delete_knowledge_source`,
  `delete_knowledge_document`
- **Evaluations** — `run_evaluation`, `list_evaluation_runs`, `get_evaluation_run`,
  `list_evaluation_datasets`, `get_evaluation_dataset`, `create_evaluation_dataset`,
  `delete_evaluation_dataset`, `add_evaluation_case`, `delete_evaluation_case`
- **Runtime** — `execute_assistant` (invoke a deployed assistant by slug),
  `run_playground` (run a single turn against a draft or pinned version to test
  prompt/model/tool changes before publishing)
- **Admin** (`mcp:admin`) — `list_members`, `update_member_role`,
  `remove_member`, `list_api_keys`, `create_api_key`, `revoke_api_key`,
  `list_provider_credentials`, `set_provider_credential`,
  `delete_provider_credential`

Tools that operate on a single organization accept a `workspaceId` (and other
ids) as arguments; for an all-organizations connection they also take an
`organizationId`.

## Managing connections

Every approved connection appears in the dashboard under **Settings → Connected
applications**, where you can review its scopes and organization and revoke it.
Revocation is immediate: outstanding access tokens stop working on the next
request, and the refresh token is invalidated too.

## Security model

- **OAuth 2.1** with PKCE, exact redirect-URI matching, and refresh-token
  rotation with reuse detection.
- **Asymmetric, short-lived access tokens** (published JWKS); the resource server
  re-checks the grant on every request, so revoking a connection takes effect
  immediately.
- **Least privilege** — deny-by-default on the intersection of the token scope
  and your role's permission; every tool call is audited.