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.

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`
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`
API key	Encrypted key	`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`
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, reconnect, 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

# Authorize by stable catalog id or custom HTTPS endpoint
polpo connections mcp connect linear
polpo connections mcp connect https://mcp.example.com/mcp

# Replace an expired/revoked authorization atomically
polpo connections mcp reconnect conn_...

Use --no-open on headless machines; the CLI still prints the authorization URL. --json never opens a browser. 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: the hosted platform owns the provider app and users can connect immediately.
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 Integrations 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`
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. The assignment updates the agent capability and its Connection grant atomically. Tools & MCPs then shows the effective runtime tools; it is not a second configuration surface. 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.

For remote MCP servers, open the agent’s Tools & MCPs page 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.

The agent stores a non-secret MCP server reference and explicit allowedTools entries such as mcp__linear__list_issues. Runtime resolves the connection secret server-side immediately before opening the MCP client. Custom tools use the same Connection inventory through ctx.connections. Use ctx.connections.getToken("provider_or_connection_id") or ctx.connections.getHeaders("provider_or_connection_id") inside defineTool code only for legacy project-scoped integrations. New multi-user tools should declare logical connections slots and call ctx.connections.require(slot). Polpo then selects exactly one active Connection from trusted user, tenant, resource, and scope-epoch context. The client and model cannot select 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","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 '{"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.

Using Connections from an application backend

Application capabilities let your trusted backend call a provider through Polpo without receiving a token or selecting a physical Connection at runtime. There are two separate contracts:

An administrator maps a logical capability to one Connection, required scopes, and allowed provider operations.
The application backend invokes only the logical capability with trusted user/tenant/resource context and a provider-relative request.

Configure a capability from the control plane:

curl -X PUT "$POLPO_URL/v1/projects/$PROJECT_ID/connect/application-capabilities/github-issues" \
  -H "Authorization: Bearer $POLPO_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "conn_...",
    "scopes": ["repo"],
    "allowedOperations": [
      {
        "methods": ["POST"],
        "pathPatterns": ["/repos/*"],
        "requiredScopes": ["repo"]
      }
    ]
  }'

Invoke it from the application backend with a project-scoped API key:

curl -X POST "$POLPO_URL/v1/projects/$PROJECT_ID/connect/capabilities/github-issues/request" \
  -H "Authorization: Bearer $POLPO_PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invocation": {
      "user": "user_123",
      "metadata": {
        "connectionScope": {
          "principal": {"type": "external_user", "id": "user_123"},
          "tenant": {"namespace": "my-app", "id": "tenant_123"}
        }
      },
      "sessionId": "session_123"
    },
    "request": {
      "method": "POST",
      "path": "/repos/acme/site/issues",
      "body": {"title": "Deployment failed"},
      "idempotencyKey": "issue-user_123-42"
    }
  }'

The runtime derives provider, scopes, operation policy, and the physical Connection exclusively from the active grant. Supplying connectionId, provider, scopes, or surface in the invocation request is rejected. POST, PUT, PATCH, and DELETE require an idempotency key. Responses contain the sanitized provider response, never credentials or the selected Connection ID.

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!,
  apiKey: process.env.POLPO_PROJECT_API_KEY!,
  projectId: process.env.POLPO_PROJECT_ID!,
});

const setup = await connect.createSetupSession({
  providerId: "github",
  audience: "end_user",
  subject: {
    type: "external_user",
    namespace: "my-app",
    id: "user_123",
  },
  scopes: ["repo"],
  returnUrl: "https://app.example.com/settings/integrations",
  application: {
    name: "Example App",
    url: "https://app.example.com",
  },
});

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.

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
`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 an implicit project link, revoke a grant targeting an inactive Connection, expire stale setup/OAuth records, and mark a stale pending Connection as errored. Missing credentials and duplicate trusted bindings are reported but never guessed or repaired automatically. Example API-key connection:

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": "api_key",
    "name": "Internal CRM",
    "apiKey": "crm_live_...",
    "scopes": ["crm:read"]
  }'

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

Connections vs Vault

Provider setup modes

Supported providers

Dashboard flow

Remote MCP onboarding

Using connections from agents

Using Connections from an application backend

End-user setup

Builder and MCP behavior

How this relates to MCP

API

Security model

​Connections vs Vault

​Provider setup modes

​Supported providers

​Dashboard flow

​Remote MCP onboarding

​Using connections from agents

​Using Connections from an application backend

​End-user setup

​Builder and MCP behavior

​How this relates to MCP

​API

​Security model

Connections vs Vault

Provider setup modes

Supported providers

Dashboard flow

Remote MCP onboarding

Using connections from agents

Using Connections from an application backend

End-user setup

Builder and MCP behavior

How this relates to MCP

API

Security model