Connect via 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), 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

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:

{
  "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.

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.

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

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.