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.

The server implementation uses Streamable HTTP with protocol 2026-07-28. Older protocol profiles receive an explicit version error. Real ChatGPT and Codex acceptance is tracked separately from the automated SDK tests; other clients have unverified compatibility. Check your instance’s release notes before treating a client as verified.

Connect and authorize

Copy the MCP endpoint from Settings → API & MCP. It ends in /mcp on your Perpensa instance. 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 your instance’s endpoint. 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.

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, change findings or create remediation 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.