When to use MCP
Use MCP to explore Permute data or run 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
Hosted connectors support MCP 2026-07-28 and the supported 2025-era Streamable HTTP handshakes, including 2025-06-18 and 2025-11-25. Local stdio requires MCP 2026-07-28. Each connection still requires authorization and current permission to use its configured resources.
Action tools carry their published schemas and behavior hints. Your client controls confirmation; calls that reach Permute execute under your current app and action permissions. Hosts with native tool search can load definitions on demand (other clients should connect to an app with a smaller action selection).
Publish a connector
- 1As an organization admin, open Settings → MCP Connectors and select Create MCP Connector.
- 2Name the connector, choose a workspace, and set Access through to Selected sources or an app.
- 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:
- 1In Claude, open Settings, select Connectors, and add a custom connector.
- 2Enter a name and paste the Permute MCP server URL. Leave OAuth client ID and secret empty.
- 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
- 1Open ChatGPT Plugins, select Add, then Add custom MCP server.
- 2Enter a name. Under Connection, select Server URL and paste the connection URL. Set Authentication to OAuth and leave Advanced OAuth settings unchanged.
- 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.
- 1Open Plugins → MCPs, select Add, and open the custom MCP form.
- 2Give the connection a name, choose Streamable HTTP, and paste the connection URL.
- 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.
Refresh your connector’s tools
If a Permute action is missing or your chat says a tool is unavailable (for example, after an app update), refresh the connection in your AI client and retry the request.
- ChatGPT web. Open ChatGPT Plugins, select your Permute connection, and choose Refresh. Check that the tool list updated, then start a new chat and select the connection again. If someone else manages the connection and you don’t see Refresh, ask them to refresh it.
- Claude web or Desktop. Open the Permute connector from Plugins or Customize → Connectors, depending on your layout. On web, choose Refresh tools list if you see it. If the button is missing or the list stays stale, disconnect and reconnect your account on the connector. Start a new chat and enable the connector again.
- Claude Code. Run
/mcp, select the Permute server, and choose Reconnect. Retry once the server is connected. - Codex CLI or desktop with a directly configured MCP server. Quit and reopen the client, then start a fresh session. Use
/mcpto check that the server and its tools are available. - Cursor IDE. Use Reload MCP Server for the Permute server if available. If the tool list stays stale, fully quit and reopen Cursor.
If the action is still missing, ask the app owner to check that it’s published and that you can run it.
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.
For role-based reads, select separate filtered Data Table or Data Flow outputs and keep broader sources restricted. The filtered-output guide covers sharing, historical data, and refresh when assignments change.
For caller-specific current-state database reads without database Read, use a published Business Action. App MCP requires confirmation for every invocation, including reads. See the managed database read example.
Available tools
Both modes provide these read-only tools:
list_sourcesandget_sourcediscover trusted tables and fields.searchfinds supporting evidence indexed from datasets and synced connectors. Hosted connections list it only when they have an eligible source.queryruns 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_appreturns the app context, viewer, and current published app revision.- Published Business Actions with
toolmetadata appear as individually named tools with their descriptions, exact schemas, and read-only, destructive, idempotence, and open-world hints. get_action_resultreads a request's status and recorded result under current access.
App connectors execute bound actions directly. Workspace creation, dataset uploads, and app authoring remain SDK or REST operations. Source selections do not grant an app's action bindings or permissions. MCP does not expose the app's assistant conversation or rendered interface.
Run an app action
- 1Ask your client to inspect the app and discover a tool whose contract fits your request. The native catalog returns up to 50 tools per page and exposes only actions you can invoke.
- 2The client calls the named action tool with
{ requestId, input }. Permute supplies the exact app and action revisions. Your client applies its confirmation policy; Permute executes the call without a separate review page or card. - 3The tool returns the recorded result. For a lost response, the client uses
get_action_resultwith the action ID and original request ID to retrieve the saved output.
Authors can publish a tool description and annotations with the action code. With no authored metadata, Permute uses the action name, schemas, and hints derived from its capabilities. Hints describe the complete operation; they do not grant permissions or predict affected records. Tool names stay stable when a new app release retains the same action revision. An older name can also work after an action update (for example, when the action adds an optional input) if the operation and approval hints still match. The action checks your current access and validates your input. If the output shape changes, the full result may appear in the text response. Refresh your connector’s tools if a tool becomes unavailable. See how to keep published actions backward compatible.
Retries and uncertain outcomes
Choose one request ID per operation and reuse it with identical input after a lost response. Completed requests return their recorded result. Current permissions and the MCP connection remain enforced during execution, delegated effects, and result reads. Requests belong to their original actor and app release.
Correct invalid input using the returned field diagnostics. Prefer an existing batch action for work across many records. If a request reports outcome_unknown, reconcile the external system before another write; Permute will not resend that uncertain external call. A new request ID can duplicate its effect.