Connections

Connections let a project authorize external systems once, then expose that access to agents and tools without putting tokens in prompts, loop JSON, or source code. Use Connections for external integrations such as GitHub, Slack, Google Drive, Telegram, Discord, WhatsApp, remote MCP servers, or API keys. The Secrets Vault is a legacy compatibility surface for existing agent-scoped secrets. Polpo provides the OAuth callback, encrypted token storage, refresh path, scope metadata, and runtime token resolution. A hosted product can provide managed provider apps; an independently operated instance can configure its own provider apps and callback URLs.

Connecting accounts from your application

An application’s users can connect accounts for an agent without signing into the Polpo dashboard. A project administrator first configures the application’s exact HTTPS origins in Connections → Application connection setup. This works with either a Polpo OAuth app or your own OAuth app. The origins identify where users return after authorization; the provider’s OAuth callback remains hosted by Polpo. Paths, wildcards, credentials, fragments and query strings are not allowed in the origin configuration. A setup’s return URL can include its own path and query. The trusted application backend creates the setup session from its authenticated user’s identity. It can return the optional Polpo setupUrl, or use the Connect SDK’s startProjectOAuthSetup and send the user directly to the provider. Creating and managing setup sessions requires a Polpo API key with platform scope. Keep that key on the backend; confirm completion through setup status instead of trusting a browser-supplied success parameter. Provider credentials remain in Polpo for the agent’s authorized capabilities.

// Trusted application server. Configure origins once as a project administrator.
await connect.configureProjectSetup(projectId, {
  returnOrigins: ["https://app.example.com"],
});
const setup = await connect.createProjectSetupSession(projectId, {
  providerId: "google_drive",
  oauthClientMode: "managed", // "customer" selects your configured OAuth app
  audience: "end_user",
  subject: { type: "external_user", namespace: "my-app", id: authenticatedUser.id },
  scopes: ["https://www.googleapis.com/auth/drive.readonly"],
  returnUrl: "https://app.example.com/settings/connections",
});
const { authorizationUrl } = await connect.startProjectOAuthSetup(setup.id);
// Return only authorizationUrl to your browser, or use setup.setupUrl instead.

The API equivalents are GET/PUT /v1/projects/:projectId/connect/setup-configuration. CLI: polpo connections setup-config show, polpo connections setup-config set --origin https://app.example.com, or --clear. Removing the last approval for a return origin stops pending setup flows using it, including a callback already exchanging tokens. Existing Connections remain intact. Origins separately approved by an OAuth app or host configuration still apply. Your trusted backend can also show an authenticated user their connected accounts and disconnect one specific account:

const owner = { namespace: "my-app", id: authenticatedUser.id };
const accounts = await connect.listProjectEndUserConnections(projectId, owner);
await connect.revokeProjectEndUserConnection(projectId, owner, connectionId);

Derive the owner from your authenticated session. The namespace, user and project must match the Connection being revoked; other accounts remain connected. Administrators can use polpo connections end-users list <user-id> --namespace my-app or polpo connections end-users revoke <user-id> <connection-id> --namespace my-app. Keep these management calls and the platform API key on the server. Use the same identity when your backend invokes the agent: pass user and metadata.connectionNamespace: "my-app", or a canonical metadata.connectionScope.principal containing { type: "external_user", namespace: "my-app", id: authenticatedUser.id }. The runtime requires the exact application namespace and user ID. It does not infer the namespace from Gmail, Drive, an email address or the selected account. A missing namespace denies access to end-user Connections. Derive these values from your authenticated application session, never from model output or unchecked browser parameters. When configuring an OAuth app for a Connector with multiple authentication methods, set authenticationId in configureProjectOAuthClient or configureOrganizationOAuthClient. The corresponding revoke helpers accept it as their optional third argument. CLI connections oauth-clients set and revoke support --authentication <id>; omitting it selects the default method.

Static credentials and MCP account ownership

API-key, public API and MCP Connections use the same audience, subject and binding contract. Set personal for a Polpo user, shared for a shared account, or end_user for a namespaced application user. A human owner alone does not make the account personal: omitted audience retains the shared default. Personal and end-user setup derives the matching principal restriction and rejects conflicts. These fields come from the authenticated control plane, never from agent arguments. The SDK exposes createProjectApiKeyConnection, createProjectPublicConnection and createProjectMcpConnection. Custom MCP setup accepts its Connector’s providerId and authenticationId; the chosen method controls authentication. The CLI equivalent is polpo connections create <public|api-key|mcp> ./connection.json. Keep credential-bearing files private and outside source control. For MCP OAuth, polpo connections mcp connect opens the dashboard for review and confirmation. It supports a catalog ID or clean HTTPS endpoint, optional --name, and --transport for custom endpoints. Advanced authentication, owner, binding, audience and scope flags cannot be transferred in that link and are explicitly rejected; session-authenticated APIs retain those contracts. MCP discovery observes tools from the actual server. Supplying tool names in creation metadata cannot grant capabilities. If the account, credential, scopes, binding or endpoint changes while discovery is running, its result is rejected; refresh the Connection and retry. A failed or stale discovery preserves the last successfully stored inventory.

Connections vs Vault

Surface	Scope	Best for
Connections	Project-level, grantable to agents	External accounts, OAuth authorizations, MCP URLs, provider API keys, channel credentials
Vault	Agent-level legacy	Existing private secrets read through `vault_get` or `vault_list`

Connections store non-secret metadata separately from encrypted tokens and API keys. List APIs, MCP metadata tools, and the dashboard never return stored secret values. New integrations use logical capabilities resolved server-side; the physical token endpoint remains an administrative compatibility surface.

Provider setup modes

Connections use an authorized project inventory, while provider setup can come from different owners. An OAuth Client is the provider application registration; a Connection is one resulting account authorization. They are deliberately separate records.

Mode	Who owns the setup?	User experience	Best for
Managed app	The hosted platform	Click Connect, approve the provider consent screen, return to Polpo	Fast onboarding in the hosted product
Instance OAuth	The deployment operator	Configure provider client id/secret once, then users click Connect	Custom branding, custom scopes, dedicated provider quota
Customer OAuth	The organization or project	Configure a provider client id, write-only secret, and approved app origins	White-label setup and customer-owned provider quota
API key	The project	Save an encrypted server-side credential	Service accounts, bot tokens, and provider keys
Remote MCP OAuth	The project user	Choose a curated server or inspect a custom HTTPS endpoint, then approve access	User-authorized remote MCP servers with PKCE and automatic refresh
Remote MCP manual	The project	Add an MCP endpoint and optional bearer/custom-header credential	CI, service accounts, and servers without browser OAuth

In OAuth modes, end users should not paste OAuth tokens into chat. The dashboard starts the OAuth flow and the server stores the resulting token encrypted. OAuth providers redirect to a single server callback:

https://api.polpo.sh/v1/connect/oauth/callback

For self-hosting, set POLPO_CONNECT_CALLBACK_URL to the exact callback URL registered in the provider console. Google and most OAuth providers require the callback URI to match exactly, including scheme, host, path, and trailing slash.

Supported providers

Polpo currently ships these provider definitions:

Provider	Auth	Provider id
GitHub	OAuth 2.0	`github`
Slack	OAuth 2.0	`slack`
Gmail	OAuth 2.0	`gmail`
Google Drive	OAuth 2.0	`google_drive`
Telegram	Bot token	`telegram`
Discord	Bot token	`discord`
WhatsApp	Cloud API token	`whatsapp`
MCP URL	URL / optional bearer auth	`mcp_url`
Generic credential (legacy)	Encrypted key without an API destination	`api_key`

Independent deployments configure OAuth provider apps with environment variables:

Provider	Client id	Client secret
GitHub	`POLPO_CONNECT_GITHUB_CLIENT_ID`	`POLPO_CONNECT_GITHUB_CLIENT_SECRET`
Slack	`POLPO_CONNECT_SLACK_CLIENT_ID`	`POLPO_CONNECT_SLACK_CLIENT_SECRET`
Gmail	`POLPO_CONNECT_GOOGLE_CLIENT_ID` or `POLPO_CONNECT_GMAIL_CLIENT_ID`	`POLPO_CONNECT_GOOGLE_CLIENT_SECRET` or `POLPO_CONNECT_GMAIL_CLIENT_SECRET`
Google Drive	`POLPO_CONNECT_GOOGLE_CLIENT_ID` or `POLPO_CONNECT_GOOGLE_DRIVE_CLIENT_ID`	`POLPO_CONNECT_GOOGLE_CLIENT_SECRET` or `POLPO_CONNECT_GOOGLE_DRIVE_CLIENT_SECRET`

Optional URL settings:

Variable	Purpose
`POLPO_CONNECT_CALLBACK_URL`	Public callback URL used in OAuth authorization and token exchange
`APP_URL` or `POLPO_DASHBOARD_URL`	Dashboard URL used after the server completes OAuth

Dashboard flow

Open a project.
Go to Connections.
Choose a provider.
Complete the OAuth flow, save an API-key connection, or add a remote MCP server URL.
Use the connections list to inspect status, scopes, owner, and whether a secret exists.

The dashboard can create, reconnect, and revoke Connections. Open View grants and activity from a Connection row to inspect its effective agent/application grants and the latest sanitized lifecycle or provider events. Credentials are never included in this activity view.

Remote MCP onboarding

The MCP catalog is curated rather than inferred from logos or vendor names. Each row reports its actual setup mode and verification state:

OAuth preview means endpoint discovery, protected-resource metadata, PKCE, and client registration were verified, while provider login and a representative tool call still require a provider test account before stable certification.
Manual setup means bearer or custom-header authentication remains available without browser OAuth.
Setup required means the provider needs a customer OAuth application, provider approval, or an instance-specific endpoint.
Conditional means Polpo can implement the protocol, but the provider restricts which hosted clients may connect.

Selecting a standard OAuth server starts Authorization Code + PKCE. Where the provider advertises Dynamic Client Registration, Polpo registers and reuses a server-side client automatically. Access and refresh tokens are encrypted and are never written into agent JSON, prompts, traces, or browser storage. Custom endpoints are inspected without credentials first. Inspection is available independently from OAuth rollout so a safe bearer/header setup remains possible. OAuth start, callback, refresh, and runtime token use are still enforced server-side by the MCP OAuth rollout and kill switch. The first catalog includes InsForge, Supabase, Linear, Stripe, Sentry, Cloudflare, Notion, Netlify, Atlassian Rovo, Vercel, GitLab, Miro, New Relic, Grafana Cloud, GitHub, Google Drive, n8n, and Figma. A catalog entry is not promoted to stable only because its URL responds. The same flow is available from the CLI:

# Inspect setup modes and current verification state
polpo connections mcp catalog

# Inspect a custom endpoint without sending credentials
polpo connections mcp inspect https://mcp.example.com/mcp

# Review and authorize by catalog id or custom HTTPS endpoint
polpo connections mcp connect linear
polpo connections mcp connect https://mcp.example.com/mcp

# Reconnect by creating a new Connection, then explicitly reassign its tools.
# Existing grants are not transferred to a potentially different account.

Use --no-open on headless machines; the CLI prints setupUrl and requiresBrowserSession: true. --json never opens a browser. For a local or custom dashboard, pass --dashboard-url http://localhost:3411 (HTTPS outside localhost). The URL contains only a setup proposal: sign in, review the endpoint, then click Inspect endpoint or Authorize. Opening the link does not start OAuth or carry the CLI key. Authorization comes from the current browser session. startProjectMcpOAuth in the SDK likewise requires a browser session, not a platform API key. Organization admins can inspect shared Connections, link each one explicitly to authorized projects, and configure organization-owned OAuth Clients. Project admins can configure project-owned OAuth Clients. Personal and end-user credentials never appear in an unrelated organization inventory. Stored secrets are write-only and are never displayed. Provider cards show how the connection is configured:

Managed app: Polpo supplies the OAuth app. Setup readiness and account verification are separate checks.
OAuth: the instance owns the provider app and users can connect immediately.
Setup required: an admin must configure provider client id/secret before users can authorize.
MCP: the project connects a remote MCP server.
Channel: the project stores bot/channel credentials.

Using connections from agents

Connections do not automatically grant every agent access. Open the agent’s Tools → Connectors tab and enable the specific provider actions it may call:

Provider	Runtime tools
GitHub	`github_list_repos`, `github_create_issue`, `github_read_file`
Slack	`slack_list_channels`, `slack_send_message`
Gmail	`gmail_search_messages`, `gmail_read_message`
Google Drive	`drive_search_files`, `drive_read_file`

At runtime, these tools resolve the project Connection server-side. The model receives the action result, not the OAuth token or API key. Connection tools should be assigned explicitly instead of via provider wildcards. A coordinated, versioned assignment operation updates the agent capability and its Connection grant. Tools shows the corresponding assignments. Connections can also be granted to one agent/tool pair. Grants make the runtime permission boundary explicit and auditable:

Create or reuse a Connection.
Grant a specific agent access to a specific connection-backed tool.
Runtime resolves only the matching connection for that tool call.

The generic grant API, polpo connections grant-slot, and the management MCP tool use the same assignment path as the dashboard. They enable the exact tool in the agent policy and activate its grant only after a conditional configuration update succeeds. Tool-name patterns such as * or http_* are rejected. Requested scopes must be available on the Connection; curated actions also require their declared scopes. Repeating the same active grant policy preserves its grant generation while checking the agent configuration again. Revocation targets the grant generation observed by the server, then removes unused tool policy. Newer assignments and agents recreated with the same name are preserved. If an update reports an uncertain outcome, inspect the current agent and grant state before retrying. Recovery after a server interruption is still a separate operational concern; this does not claim a transaction spanning the control and agent databases. For remote MCP servers, open the agent’s Tools tab and select MCP:

Connect a new MCP server or reuse an existing MCP Connection.
Discover the server’s tools.
Enable only the discovered tools the agent should call.

Managed MCP uses the account’s Connection grants and explicit allowedTools entries such as mcp__linear__list_issues. Managed execution uses a host-owned capability and checks the live agent identity and grant before provider requests. Disabling the runtime gate does not enable direct MCP credential access. Public MCP servers also use Connections in managed; standalone OSS hosts can configure direct MCP transports independently. Each account has its own tool switches. Accounts can share a tool namespace; assigning the same tool to several accounts requires matching tool definitions and distinct authorized user or resource contexts. Polpo resolves the account from the trusted invocation context. Remove access on an agent removes only that agent’s grants for the account. Other agents keep their access. Revoke the Connection from the project Connections page when you want to disconnect the account itself. Bulk updates report partial failures and reload the saved grants; retrying updates only the remaining assignments. Pending assignments and tools no longer returned by discovery can also be removed. Custom tools declare logical connections slots with mode: "gateway" and use ctx.connections.require(slot).request(...). Polpo selects one authorized account from trusted invocation context. Provider credentials stay outside the sandbox. Gateway slots cannot call getToken, getKey, or getHeaders. Direct legacy_credentials slots also remain available when a tool needs a native credential, with separate operator consent for each exact slot. Changing tool code does not grant credential access or turn a denied gateway into direct access. See Custom Tools for both execution modes. The model cannot choose or replace the physical Connection ID. Bind a Connection to a non-secret application scope, then grant the custom tool access to it:

polpo connections bind "$CONNECTION_ID" --binding '{
  "principal":{"type":"external_user","namespace":"sitoinchat","id":"user_123"},
  "tenant":{"namespace":"sitoinchat","id":"tenant_123"},
  "resource":{"namespace":"sitoinchat","type":"site","id":"site_456"},
  "scopeEpoch":"9"
}'

polpo connections grant-slot "$CONNECTION_ID" \
  --agent leo \
  --tool site_update \
  --scope site:read site:write

polpo connections readiness \
  --agent leo \
  --tool site_update \
  --slot siteApi \
  --provider sitoinchat \
  --scope site:read site:write \
  --user user_123 \
  --metadata '{"connectionNamespace":"sitoinchat","tenantId":"tenant_123","siteId":"site_456","scopeEpoch":9}'

readiness verifies unique resolution without returning the selected Connection ID or any credential. Use polpo connections grants to inspect grants and polpo connections revoke-slot <grant-id> to revoke one.

Applications using agents

Application backends can initiate setup for their users and invoke authorized agents with trusted user context. Connections give those agents capabilities; a standalone provider proxy for application backends is outside the current product scope.

End-user setup

A trusted application backend can create an opaque, short-lived setup session for one immutable external user and resource binding. The browser receives only the setup URL; it cannot change the trusted owner, tenant, site, scopes, or return origin.

import { PolpoConnectClient } from "@polpo-ai/client-sdk";

const connect = new PolpoConnectClient({
  baseUrl: process.env.POLPO_URL!,
  headers: { Authorization: `Bearer ${process.env.POLPO_PLATFORM_API_KEY!}` },
});

const setup = await connect.createProjectSetupSession(process.env.POLPO_PROJECT_ID!, {
  providerId: "gmail",
  oauthClientMode: "managed",
  audience: "end_user",
  subject: {
    type: "external_user",
    namespace: "my-app",
    id: "user_123",
  },
  returnUrl: "https://app.example.com/settings/integrations",
  application: {
    name: "Example App",
    url: "https://app.example.com",
  },
});

Keep the platform key on the trusted backend. Configure the project’s approved return origins before creating a setup session. Resolve the external user from your application session; never accept the owner identity directly from browser input. Managed mode uses Polpo’s OAuth app; customer mode uses a configured customer OAuth Client. Embedded MCP OAuth uses a reusable MCP client configuration instead of accepting server URLs or client credentials from the end user’s browser. The trusted backend selects that configuration when creating the setup session; the end user can complete the resulting consent flow without a Polpo dashboard session. The embedded page shows the requesting application and requested scopes. It supports connect and cancel. Setup status is safe to poll and never exposes the trusted binding. Completed setup produces a separately owned Connection linked only to the approved project.

Reusable MCP OAuth setup

An MCP OAuth configuration identifies the server, transport and client registration. It is separate from each user’s authorized Connection. Supported registrations are dynamic, metadata_document and pre_registered; the MCP authorization server must support the chosen method. Cloud derives the owner and provider callback from the authenticated project or organization route. In the dashboard, open Connections → MCP OAuth setups → Configure MCP OAuth. Organization administrators can manage organization-owned setups from Organization → MCP OAuth setups. The form supports all three registrations, editing and revocation. The setup ID can be copied from the table for SDK or CLI use. Saving a setup does not connect an account. For a registered client, Server default preserves an unspecified client authentication method. Leaving the secret empty retains it only when the server, transport, Connector, Connector authentication method and Client ID are unchanged. Changing that identity requires a new secret or an explicit No client secret selection. Concurrent edits require reloading the saved setup before saving or revoking it. The callback is controlled by the host. Local development supports loopback callbacks; production Cloud callbacks require HTTPS. MCP resource URLs and public client metadata URLs retain their HTTPS requirements.

{
  "providerId": "mcp_url",
  "name": "Company MCP",
  "resourceUrl": "https://mcp.example.com/mcp",
  "transport": "http",
  "registration": { "mode": "dynamic", "clientName": "Example App" },
  "returnOrigins": ["https://app.example.com"]
}

Save this configuration in a local JSON file, then use the CLI:

polpo connections mcp configurations create ./mcp-oauth.json --json
polpo connections mcp configurations list --json
polpo connections mcp configurations update <id> ./mcp-oauth.json --revision <revision>
polpo connections mcp configurations revoke <id> --revision <revision>

Add --organization <id> to manage an organization-owned configuration. Updates and revocation require the last observed revision; reload after a conflict. Preregistered client secrets belong in the private configuration file, never in command-line arguments or agent messages. Listing configurations never returns those secrets. The Connect SDK exposes listMcpOAuthConfigurations, createMcpOAuthConfiguration, updateMcpOAuthConfiguration and revokeMcpOAuthConfiguration. A trusted backend then calls createProjectSetupSession with providerId: "mcp_url", the returned configurationId, oauthClientMode: "customer" and the same trusted user, audience and return URL fields as the API OAuth example. Managed mode requires an explicitly provided Polpo configuration; it does not silently reuse a customer configuration. Creating a configuration does not authorize an account. Each consent produces its own Connection. Revoking the configuration prevents new setup and credential delivery through that configuration; it does not revoke consent at the provider. The separate manual MCP setup flow still requires the initiating Polpo browser session.

Builder and MCP behavior

Builder and MCP clients can inspect connection availability, but they cannot create secrets in a transcript.

Tool	Purpose
`polpo_connections_providers`	List configured providers and whether OAuth is configured
`polpo_connections_list`	List non-secret project connections by provider/status
`polpo_connections_links`	List explicit project visibility links
`polpo_connections_grants`	List active or revoked agent and application grants
`polpo_connections_events`	List sanitized lifecycle and request events
`polpo_connections_capabilities`	List logical application capabilities
`polpo_connections_reconcile`	Dry-run or explicitly apply deterministic state repairs
`polpo_connections_bind`	Bind a Connection to trusted principal, tenant, resource, and epoch attributes
`polpo_connections_grant_slot`	Grant an agent/custom-tool pair a logical Connection slot
`polpo_connections_revoke_slot`	Revoke a logical slot grant

If a user asks the builder to add GitHub, Slack, Drive, MCP, or an API-key credential, it should list provider status and navigate the user to Connections or the agent Integrations tab. It should not ask the user to paste tokens into chat.

How this relates to MCP

Connections are independent from MCP, but they can power MCP use cases:

MCP as a provider: mcp_url stores a remote MCP server URL and optional bearer credential so Polpo can discover and call tools through the same connection inventory.
OAuth providers: GitHub, Slack, and Google Drive use OAuth directly; they do not require MCP.
Polpo MCP tools: tools such as polpo_connections_list expose non-secret connection metadata to builders and external MCP clients. They are not a backdoor for token access.

In practice: use OAuth/API-key Connections for provider credentials; use mcp_url when the integration is already exposed as a remote MCP server.

API

Connections are project-scoped:

Method	Path	Description
`GET`	`/v1/projects/{projectId}/connect/providers`	List configured providers
`GET`	`/v1/projects/{projectId}/connect/connections`	List public connection metadata
`GET`	`/v1/projects/{projectId}/connect/health`	Check links, grants, OAuth Clients, and secret readiness
`POST`	`/v1/projects/{projectId}/connect/reconcile`	Dry-run or apply deterministic Connection state repairs
`GET`	`/v1/projects/{projectId}/connect/oauth-clients`	List project-owned OAuth Clients without secrets
`PUT`	`/v1/projects/{projectId}/connect/oauth-clients/{providerId}`	Configure or rotate a project OAuth Client
`DELETE`	`/v1/projects/{projectId}/connect/oauth-clients/{providerId}`	Revoke a project OAuth Client
`POST`	`/v1/projects/{projectId}/connect/connections/api-key`	Store an encrypted API-key connection
`POST`	`/v1/projects/{projectId}/connect/connections/mcp`	Store a remote MCP server connection
`GET`	`/v1/projects/{projectId}/connect/mcp/catalog`	List curated MCP entries, setup modes, and verification state
`POST`	`/v1/projects/{projectId}/connect/mcp/inspect`	Safely inspect OAuth metadata for a custom HTTPS MCP endpoint
`POST`	`/v1/projects/{projectId}/connect/mcp/oauth/start`	Start MCP OAuth with PKCE and the selected client-registration mode
`GET`	`/v1/projects/{projectId}/connect/mcp-oauth-configurations`	List reusable MCP OAuth configurations without secrets
`POST`	`/v1/projects/{projectId}/connect/mcp-oauth-configurations`	Create a reusable MCP OAuth configuration
`PUT`	`/v1/projects/{projectId}/connect/mcp-oauth-configurations/{id}`	Update using `expectedRevision` in the request body
`DELETE`	`/v1/projects/{projectId}/connect/mcp-oauth-configurations/{id}?expectedRevision={revision}`	Revoke the observed configuration revision
`PATCH`	`/v1/projects/{projectId}/connect/connections/{connectionId}`	Update a name, stored credential, channel credentials, or non-OAuth granted scopes
`POST`	`/v1/projects/{projectId}/connect/connections/{connectionId}/mcp/discover`	Discover tools from a remote MCP server connection
`POST`	`/v1/projects/{projectId}/connect/connections/{connectionId}/reconnect`	Replace an OAuth authorization without revoking the active Connection first
`GET`	`/v1/projects/{projectId}/connect/grants`	List agent/tool grants for project connections
`POST`	`/v1/projects/{projectId}/connect/grants`	Grant one agent/tool access to a connection
`POST`	`/v1/projects/{projectId}/connect/grants/{grantId}/revoke`	Revoke an agent/tool connection grant
`POST`	`/v1/projects/{projectId}/connect/readiness`	Verify a trusted slot against an invocation scope without revealing credentials
`GET`	`/v1/projects/{projectId}/connect/events`	List connection audit events
`GET`	`/v1/projects/{projectId}/connect/application-capabilities`	List logical application capability grants
`PUT`	`/v1/projects/{projectId}/connect/application-capabilities/{capabilityId}`	Configure scopes and allowed operations for a logical application capability
`DELETE`	`/v1/projects/{projectId}/connect/application-capabilities/{capabilityId}`	Revoke an application capability
`POST`	`/v1/projects/{projectId}/connect/capabilities/{capabilityId}/request`	Execute a provider-relative request from a trusted application backend
`POST`	`/v1/projects/{projectId}/connect/oauth/start`	Start an OAuth authorization
`GET`	`/v1/connect/oauth/callback`	Canonical OAuth provider callback
`POST`	`/v1/projects/{projectId}/connect/oauth/callback`	Legacy dashboard callback for local/custom flows
`POST`	`/v1/projects/{projectId}/connect/connections/{connectionId}/token`	Resolve a scoped token for runtime use
`POST`	`/v1/projects/{projectId}/connect/connections/{connectionId}/actions/{actionId}`	Execute a provider action through a connection
`POST`	`/v1/projects/{projectId}/connect/connections/{connectionId}/revoke`	Revoke a connection

Organization admins use /v1/orgs/{orgId}/connect/connections for shared inventory and /v1/orgs/{orgId}/connect/oauth-clients for customer OAuth Client administration. Reconciliation defaults to dry-run:

polpo connections health --json
polpo connections reconcile --json
polpo connections reconcile --apply --json

It can recreate a missing implicit project link, revoke a grant targeting an inactive or inaccessible Connection, expire unused setup/OAuth records, and mark a stale pending Connection as errored. It preserves explicit unlink decisions and newer changes made while the audit runs. Missing credentials and duplicate trusted bindings are reported but never repaired automatically. Repairs count only rows actually changed. An issue can remain repaired: false when another request changed its target; inspect the next dry-run before retrying. Reports with truncated: true cover only the configured scan limit, not the whole project. Referenced Connections are checked independently of that limit, so an account outside the scanned page is never treated as missing. Setup sessions already consumed by a callback, live MCP OAuth claims, and completed MCP callback receipts are preserved. Reconciliation also reports interrupted agent assignments and revocations in assignments.operations. With --apply, it processes operations idle for at least 60 seconds: it resumes an assignment only while the original administrator, Connection permissions and agent identity remain valid, rolls back a cancelled assignment, or finishes recorded revocation cleanup. Explicit revocations and newer agent edits are preserved. Private policies and credentials are never included in these reports. Cloud operators can enable scheduled recovery separately for selected projects. Where enabled, failed operations retry with increasing delays, up to 12 automatic attempts; unresolved intent remains available for manual reconciliation and appears as requires_attention in a dry-run report. Automatic recovery uses the same permission and agent identity checks as manual recovery. Completed private operation records are retained for 30 days; pending operations are not removed by that retention policy. This maintenance is disabled by default until the hosted rollout is configured. Outcomes include succeeded, compensated, revoked, superseded, deferred (retry after the host or storage recovers), and requires_attention. revoked refers to the selected grant generation; newer edits or a replacement agent are preserved. superseded means a newer grant generation prevented the older revocation. If the tenant is unavailable after permission was withdrawn, cleanup stays queued and never reactivates that permission. Disabling a capability across multiple accounts withdraws all selected grants before starting tenant cleanup. Example custom API integration with an API key: Register the non-secret Connector definition first. Replace the example origin, path and header with those of your service. This definition allows only GET /contacts; it does not grant an agent access by itself. These control-plane requests require a Polpo API key with platform scope.

curl -X POST "$POLPO_URL/v1/projects/$PROJECT_ID/connect/connectors" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 2,
    "id": "internal_crm",
    "name": "Internal CRM",
    "source": "custom",
    "protocol": "http_api",
    "defaultAuthenticationId": "key",
    "authentication": [{
      "id": "key",
      "type": "api_key",
      "injection": { "mode": "header", "name": "X-API-Key" }
    }],
    "scopes": [{ "id": "crm:read", "label": "Read contacts" }],
    "http": {
      "origins": ["https://crm.example.com"],
      "allowedMethods": ["GET"],
      "allowedPathPatterns": ["/contacts"]
    }
  }'

Then create a Connection selecting that definition and its authentication method:

curl -X POST "$POLPO_URL/v1/projects/$PROJECT_ID/connect/connections/api-key" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "internal_crm",
    "authenticationId": "key",
    "name": "Internal CRM",
    "apiKey": "crm_live_...",
    "scopes": ["crm:read"]
  }'

The SDK equivalents are registerProjectConnectorDefinition and createProjectApiKeyConnection. Assign the Connection to an agent’s tool through a logical slot and grant, as described in Custom Tools. Polpo injects the key at the allowed destination when that tool runs. The legacy api_key provider stores a credential without a destination policy; it does not create a callable API integration. Example remote MCP connection:

curl -X POST "$POLPO_URL/v1/projects/$PROJECT_ID/connect/connections/mcp" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Linear MCP",
    "url": "https://mcp.linear.app/mcp",
    "transport": "http",
    "auth": "bearer",
    "bearerToken": "lin_..."
  }'

Discover tools from that server:

curl -X POST "$POLPO_URL/v1/projects/$PROJECT_ID/connect/connections/$CONNECTION_ID/mcp/discover" \
  -H "Authorization: Bearer $POLPO_API_KEY"

Update the granted scopes of a non-OAuth Connection without replacing its stored credentials:

curl -X PATCH "$POLPO_URL/v1/projects/$PROJECT_ID/connect/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["messages:write"]}'

The update replaces the complete scope set. Passing [] explicitly revokes all local grants. OAuth scopes must be changed by reconnecting the provider because changing the stored scope list does not change the authorization held by an OAuth token. Updating scopes never rotates or returns the Connection token, app secret, or webhook verify token. Example non-secret list response:

{
  "ok": true,
  "data": [
    {
      "id": "conn_...",
      "providerId": "github",
      "name": "Engineering GitHub",
      "authType": "oauth2",
      "status": "active",
      "grantedScopes": ["repo"],
      "hasSecret": true
    }
  ]
}

Security model

Tokens and API keys are encrypted before storage.
Public connection records include hasSecret, not the secret value.
OAuth state is project-scoped and expires automatically.
MCP tools are read-only for connection metadata.
Secret creation happens in the dashboard or through authenticated API calls, not through LLM chat.
Agent prompts, transcripts, traces, and mcpServers config must not contain raw MCP bearer tokens.
Application runtime requests cannot choose Connection IDs, providers, OAuth scopes, or execution surfaces.
Unsafe application gateway operations require an idempotency key; audit rows store a policy identifier, status, latency, and sanitized error code rather than payloads or provider paths.

Getting Started

Platform

Agents

Orchestration

Connecting accounts from your application

Static credentials and MCP account ownership

Connections vs Vault

Provider setup modes

Supported providers

Dashboard flow

Remote MCP onboarding

Using connections from agents

Applications using agents

End-user setup

Reusable MCP OAuth setup

Builder and MCP behavior

How this relates to MCP

API

Security model

​Connecting accounts from your application

​Static credentials and MCP account ownership

​Connections vs Vault

​Provider setup modes

​Supported providers

​Dashboard flow

​Remote MCP onboarding

​Using connections from agents

​Applications using agents

​End-user setup

​Reusable MCP OAuth setup

​Builder and MCP behavior

​How this relates to MCP

​API

​Security model

Connecting accounts from your application

Static credentials and MCP account ownership

Connections vs Vault

Provider setup modes

Supported providers

Dashboard flow

Remote MCP onboarding

Using connections from agents

Applications using agents

End-user setup

Reusable MCP OAuth setup

Builder and MCP behavior

How this relates to MCP

API

Security model