MCP
Connections
Source: orchestration/mcp-gateway/tools-connections.ts (ConnectionsSchema, plungeaiConnections), orchestration/mcp-gateway/ops/connections.ts (the store, the subject rule, the connect link), core/core-secrets/UserCredentialsService.ts, core/core-secrets/connect-token.ts, orchestration/api-gateway/routes/connections.ts (the REST twin).
plungeai_connections manages the accounts your agents act through, action for action the One API's /v1/connections. Credentials are stored encrypted on the compliance database and never come back out: a list shows provider, method, status and when, nothing else. Full parameter table: 14.22.
17.1 Whose account: on_behalf_of
Without on_behalf_of a call acts on your own account. With it, it acts on one of your customers: the id is yours to choose (1–128 characters of A-Z a-z 0-9 _ . -, no ..), and the row is kept under your account, so no other key can reach it. An empty or malformed value is refused (invalid_on_behalf_of), never read as "me".
17.2 Actions
action | Needs | REST twin | Answer (structuredContent) |
|---|---|---|---|
list | optional on_behalf_of | GET /v1/connections | {connections: [{provider, on_behalf_of, method, status, connected_at}]}. Every list is written to the secrets audit log |
add | provider, api_key; optional api_secret, on_behalf_of | POST /v1/connections/{provider} | {provider, on_behalf_of, status: "connected"}. Where the platform has a probe for the provider, the key is checked first; a key the provider rejects is credential_rejected |
remove | provider; optional on_behalf_of | DELETE /v1/connections/{provider} | {provider, on_behalf_of, status: "disconnected"}; nothing to remove is connection_not_found |
link | provider; optional return_url (https), on_behalf_of | POST /v1/connections/{provider}/link | {url, expires_at}: a signed Studio link, single use, valid 15 minutes. Send it to whoever owns the account; they connect there (OAuth or key) and return to return_url |
provider must be a provider the platform can connect: a key-based one (stripe, openai, apollo, custom, …), an OAuth one (github, google-gmail, …) or one an agent's connection prompt names. Anything else is not_found unknown_provider. The key and secret are redacted from the activity log like every other secret-named argument.
17.3 Refusals
The same shape as 16.4: isError: true text <word>: <message> (<code>) and structuredContent.error = {status, code, message}.
status word | Codes |
|---|---|
invalid | invalid_params (no provider), missing_api_key, credential_rejected, invalid_on_behalf_of, invalid_return_url |
forbidden | owner_not_found (link from a key whose user account is gone) |
not_found | unknown_provider, connection_not_found |
unavailable | connections_unavailable (the credential store is not reachable from this deployment) |
Try asking:
- "What accounts have I connected?" →
list - "Send my customer acme-42 a link to connect their GitHub." →
linkwithon_behalf_of: "acme-42" - "Disconnect Stripe." →
remove
List your connections (read-only):
curl -s https://mcp.plungeai.com/v1 \
-H "Authorization: Bearer $PLUNGE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_connections","arguments":{"user_request":"what accounts have I connected?","action":"list"}}}'Make a connect link for a customer. This signs a link (not verified here):
curl -s https://mcp.plungeai.com/v1 \
-H "Authorization: Bearer $PLUNGE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_connections","arguments":{"user_request":"send acme-42 a link to connect GitHub","action":"link","provider":"github","on_behalf_of":"acme-42","return_url":"https://app.example.com/connected"}}}'