MCP connectors

When to use MCP

Use MCP to explore Permute data or propose an app's actions from Claude or another compatible client. Choose selected sources for read-only analysis, or a hosted app for its permitted data and published action contracts. Use the TypeScript SDK for programmatic integrations and the REST API for direct HTTP control.

Client requirements

Permute requires MCP 2026-07-28. Your AI app must support this protocol version; older clients cannot connect. Reconnecting or signing in again does not upgrade a client's protocol support. The setup steps below apply to clients that meet this requirement.

In-chat approval uses an MCP Apps review card when supported, or the client's native confirmation prompt (form elicitation). Compatible clients without either feature use the Permute review page.

Publish a connector

1. 1As an organization admin, open Settings → MCP Connectors and select Create MCP Connector.
2. 2Name the connector, choose a workspace, and set Access through to Selected sources or an app.
3. 3For Selected sources, choose the queryable sources to expose. For an app, select a live, published app that uses Permute sign-in. Create the connector and copy its stable server URL.

https://api.permute.ai/mcp/mcps_...

App connectors use the app's current grants and published action bindings. Before connecting, grant the app access to its intended resources, bind any actions to published action revisions, and publish the app. The connecting user also needs app access and permission to use each resource. See the app deployment guide for app setup.

App connectors work with the app's chat overlay disabled, and an app with no readable sources can still offer permitted actions. Password-demo apps can't connect. A connector's workspace and access mode are fixed at creation; create a new connector to target a different app or switch modes.

Connect from Claude

After creating a connector, select the Claude tab and then Open Claude in the connection dialog to prefill its name and server URL. You can also copy an existing connector's URL and configure it manually:

1. 1In Claude, open Settings, select Connectors, and add a custom connector.
2. 2Enter a name and paste the Permute MCP server URL. Leave OAuth client ID and secret empty.
3. 3Sign in to Permute, review the workspace and selected sources or app, and approve the connection. App actions need a separate confirmation for each request.

Connect from ChatGPT

1. 1Open ChatGPT Plugins, select Add, then Add custom MCP server.
2. 2Enter a name. Under Connection, select Server URL and paste the connection URL. Set Authentication to OAuth and leave Advanced OAuth settings unchanged.
3. 3Review the connection notice, select I understand and want to continue, then Create as a plugin. Sign in to Permute when asked, then enable the connection in your chat.

ChatGPT packages the MCP connection as a plugin. Account and workspace policies may limit availability; see the ChatGPT connection guide.

ChatGPT desktop and Codex

The desktop form uses the same connection URL, with different setup fields.

1. 1Open Plugins → MCPs, select Add, and open the custom MCP form.
2. 2Give the connection a name, choose Streamable HTTP, and paste the connection URL.
3. 3Leave the other fields blank. Save, then sign in to Permute and review the app, data sources, and business actions before allowing the connection.

When the client shows “Authentication complete,” close that browser tab and return to your chat. See the official configuration guide for CLI and IDE setup.

Connect from other MCP clients

Add the same connector URL as a remote Streamable HTTP server. Do not enter a Permute API key or configure OAuth client credentials. The client should discover Permute OAuth and open the sign-in and consent flow.

Authorization and access scope

Hosted MCP uses OAuth with each person's own Permute account; it doesn't accept Permute API keys. Every request (including requests from existing connections) checks current resource permissions. Connecting never grants new resource permissions.

• Selected sources: access is limited to the selected sources and the user's current workspace permissions.
• Hosted app: source reads require both a current app grant and the user's permission. Actions also require a published binding in the app release. An action grant doesn't grant access to its underlying sources.

Available tools

Both modes provide these read-only tools:

• list_sources and get_source discover trusted tables and fields.
• search finds supporting evidence and citations.
• query runs read-only SQL when exact source and table names are known.

Selected-source connectors also provide answer and get_answer for durable interpreted analysis. App connectors provide the following tools instead:

• get_app returns the app context, viewer, and current published app revision.
• list_actions discovers permitted action contracts, their input schemas, and declared capabilities.
• propose_action prepares a request and asks for your confirmation. Supporting clients can review and run it in chat; other clients return a Permute review link.
• get_action_request reads a request's status and recorded result, subject to current access.

App connectors expose no direct execution or app-authoring tool. Workspace creation and dataset uploads remain SDK or REST operations. Selecting the same sources as an app doesn't give a source connector that app's grants or action bindings. MCP doesn't expose the app's assistant conversation or rendered interface.

Review and run an app action

1. 1Ask the client to inspect the app and list its actions. Choose an action whose contract fits your request.
2. 2The client calls propose_action with the discovered actionId and appRevisionId, a UUID requestId, and the exact input. Permute validates and stores the request, then asks for confirmation in supported clients or returns a review URL. Pending proposals expire after 15 minutes and haven't run.
3. 3Review the exact input and declared capabilities. In an inline card, select Confirm or Cancel. With a native prompt, use the client's confirmation button to run it; decline or cancel to dismiss. Otherwise open the review URL, sign in to Permute as the same user, and select Confirm and execute or Dismiss. Every action requires confirmation, including read-only actions.
4. 4Use get_action_request to check completion and retrieve the recorded result. Outputs larger than 40 KB return a completion marker without the output.

Declared capabilities describe what the action can do; they aren't a preview of affected records. Approval uses your authenticated identity and the exact prepared request (including its app and action releases). Cards require MCP Apps support; native prompts require form elicitation. Compatible clients without either feature and requests too large for a native prompt use the Permute review page. Adding an approval flag to tool arguments can't confirm a request.

In-chat execution continues to check the confirming MCP connection, app policy, and current permissions. For web reviews, keep the originating MCP session active until you first confirm; execution then uses the confirming Permute login. Disconnecting doesn't undo completed effects.

Retries and uncertain outcomes

Reuse the same request ID, input, and revision IDs when retrying a proposal. If a confirmation response is lost, retry from the same card or native request, or reopen the same review URL for a web confirmation. Completed requests return their recorded result. Publishing a new app release doesn't change an existing request's reviewed bindings; current permissions still apply.

If a request reports outcome_unknown, reconcile the external system before starting another write. Permute won't resend that uncertain external call. Creating a new request ID can duplicate its effect.