Connect an assistant with MCP

Use a Perpensa MCP connection to read existing dependency results, explain a finding or update, and evaluate a CI gate. Export and product feedback require separate permissions. You need a Pro or Team organization and membership in it.

For the private read-only workflows, see Use Perpensa skills in Codex. Connecting MCP supplies tools and data; installing a versioned skill supplies the workflow instructions. The two steps have separate verification requirements.

The MCP endpoint uses Streamable HTTP with protocol 2026-07-28. Clients on an older protocol version receive an explicit version error.

Quick connect (Prompt / Codex CLI / Claude Code / Grok Build / ChatGPT)

Copy one of the snippets below to connect your coding agent or assistant in a few seconds. If your organization uses another Perpensa address, replace https://perpensa.app/mcp with the MCP endpoint URL shown in Settings → API & MCP.

Coding agents and LLM tools that index documentation can also read /llms.txt (available at both https://perpensa.app/llms.txt and https://docs.perpensa.app/llms.txt) for a single-file Markdown summary of Perpensa capabilities, read-only MCP tools, OAuth scopes, and guide links.

1. Prompt (Claude Code, Cursor, Windsurf, Codex)

Paste this prompt into your coding agent so it configures the Perpensa MCP server and runs a first read-only query:

Set up the Perpensa MCP server (Streamable HTTP with OAuth):
- Server name: perpensa
- URL: https://perpensa.app/mcp
Once connected, use list_organizations and list_priorities to list our Fix now priorities for Production, then call explain_finding or explain_update on the first item according to its kind (if the queue is non-empty).

2. Codex CLI

codex mcp add perpensa --url https://perpensa.app/mcp
codex mcp login perpensa

3. Claude Code

claude mcp add --transport http perpensa https://perpensa.app/mcp
claude mcp login perpensa

Or run /mcp in a Claude Code session to complete the OAuth login.

4. Grok Build

grok mcp add --transport http perpensa https://perpensa.app/mcp
grok mcp doctor perpensa

5. ChatGPT (Custom MCP server)

In ChatGPT, open Plugins → + → Add custom MCP server, enter https://perpensa.app/mcp with OAuth authentication, complete the consent screen, and test with:

Use Perpensa to list my organizations, then list the priorities for Production and explain the first item using explain_finding or explain_update based on its kind.

Connect and authorize

Copy the MCP endpoint from Settings → API & MCP. It ends in /mcp. Add that HTTPS URL in your client and choose OAuth. Sign in with your usual Perpensa account. On the consent screen, review the client, endpoint, permissions, organizations and applications, then select Authorize or Deny. Check the client identifier and callback destination, not just its declared name. Dynamically registered clients are marked Unverified client (DCR); CIMD shows the metadata domain. Names are supplied by the client.

Read results and Check CI start enabled. Export and Send feedback start disabled. All my eligible organizations and their applications includes future organizations and applications you can access. Choose individual applications to keep the connection limited to them. Each tool request names one organization; V1 has no consolidated view across organizations.

A new connection reserves one machine access in each admitted organization, even before use. Connections and API tokens share the organization’s quota: five for Pro and 25 for Team. A refusal in one organization does not block another. After a quota refusal, activate the access in Settings when a slot becomes available.

OAuth consent lasts 90 days. Reconnect and select the existing connection to renew it without creating another quota slot. Select Renew for 90 days to extend the deadline. Approving wider permissions without renewal keeps the existing deadline. Editing the parent access never silently widens an existing consent. Denying consent creates no access and consumes no slot. Authorizing an existing connection replaces its previous consent immediately. If client setup then fails, reconnect and select the same connection again; no second slot is needed. Settings shows the connection limits; its current consent can be narrower. Reduce those limits immediately with Edit limits. To authorize additional permissions or applications, reconnect and approve the consent. If a new setup is abandoned, revoke the unused connection in Settings to release its slot.

The client renews its short-lived access token automatically within the consent period. If an older connection asks you to sign in again after about 15 minutes, follow the ChatGPT steps below. For other clients, refresh the server configuration and reconnect, selecting the existing connection when offered. Keep Renew for 90 days unchecked to preserve the original deadline.

ChatGPT

On ChatGPT web, open Plugins, select + → Add custom MCP server, enter the endpoint, and choose OAuth. Choose CIMD client identification when offered; DCR is the fallback. Complete authorization, create the personal plugin and install it. Select it with @ in a conversation. Workspace restrictions may limit this flow. See OpenAI’s connection guide.

If an older personal plugin asks you to sign in again after about 15 minutes, create a new one through Plugins → + → Add custom MCP server, using the same endpoint and OAuth. The older plugin can keep requesting permissions without permission to refresh the connection, even after reconnecting or refreshing its tools. During authorization, select the existing connection when offered and leave Renew for 90 days unchecked. Reusing it requires the same client identifier, shown on the consent screen; the server address alone is not enough. ChatGPT’s CIMD identification keeps this identifier stable. If DCR registration gives the new plugin a different identifier, create a new connection instead: it needs a machine-access quota slot in each selected organization, and the old connection remains separate. Install and select the new personal plugin in ChatGPT and Codex desktop. Once it works, uninstall the old personal plugin in ChatGPT to avoid selecting it by mistake. Do not revoke a reused connection in Perpensa Settings → API & MCP: revoking it also blocks the new plugin.

Ask: “Use Perpensa to list my organizations, then list the priorities for application <application_id> in organization <org_id>. Explain the first finding.” No directory publication or embedded application UI is required.

Codex

Add the endpoint and log in through OAuth:

codex mcp add perpensa --url https://perpensa.example/mcp
codex mcp login perpensa
codex mcp list

Replace the example URL with the endpoint shown in Settings. Finish the browser consent, then use /mcp to inspect the connection. If diagnosing registration, codex mcp login perpensa --oauth-client-registration cimd selects CIMD and --oauth-client-registration dcr selects the fallback. See the official MCP guide.

Claude Code

Add the endpoint as a remote HTTP server and log in through OAuth:

claude mcp add --transport http perpensa https://perpensa.example/mcp
claude mcp login perpensa
claude mcp list

Replace the example URL with the endpoint shown in Settings. Instead of claude mcp login, you can run /mcp in a Claude Code session to authenticate and inspect the connection. Add --scope project to share the server through .mcp.json, or --scope user for all your projects (do not commit a real token in .mcp.json). For headless or CI use, create a scoped API token in Settings → API & MCP and pass it as a header instead of OAuth:

claude mcp add --transport http perpensa https://perpensa.example/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

See the official Claude Code MCP guide.

Grok Build

Add the endpoint as a remote HTTP server:

grok mcp add --transport http perpensa https://perpensa.example/mcp
grok mcp list
grok mcp doctor perpensa

Replace the example URL with the endpoint shown in Settings. Grok Build opens the browser OAuth consent on first use; if it does not, run /mcps, select perpensa and press i. Add --scope project to share the server with the repository. For headless or CI use, pass a scoped API token as a header:

grok mcp add --transport http perpensa https://perpensa.example/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Do not commit a real token with --scope project. See the official Grok Build MCP guide.

Results, exports and refusals

Tools return the same business data as the API, including scope, freshness, coverage and request identifiers. CI returns compliant, non_compliant or indeterminate; treat indeterminate as blocked by default. Tools cannot start scans, accept risks or change findings. Perpensa never opens pull requests.

Exports are asynchronous. Keep one idempotency_key for retries, poll get_export_status, and use read_export to retrieve exact, cursor-based blocks. The blocks contain exported content rather than an assistant’s summary. Files expire after 24 hours. You can also download an authorized export in Perpensa’s interface. Feedback uses the same destination as the interface and a separate idempotency key.

The API and MCP share access counters and concurrency limits. When throttled, wait for the returned retry delay; polling and export blocks count as requests. Revocation, expiry, departed membership, application removal, member restrictions and persistent organization exclusions apply to subsequent calls. An administrator can disable MCP for one organization while leaving its API access available. A suspended access keeps its quota slot. Renewals preserve administrator exclusions.