Remote MCP

​

Connect a server

1. Open the agent’s Tools page and choose Add tool.
2. Select a service and use its recommended sign-in method or supported API-key alternative. For Custom MCP server, choose authentication and enter a connection name and public HTTPS endpoint under Connection details.
3. Choose Connect for an API key, or Continue to sign in for OAuth. Formation saves this agent’s credential, discovers the catalog, and activates every supported tool, including writes, for the next turn.
4. Optionally choose Manage tools to exclude tools, then Save tool preferences. Select all, Deselect all, Select read-only, and individual checkboxes change this optional selection. Saving with every tool turned off is allowed.

​

Multiple accounts at one endpoint

​

Connect with OAuth

1. In Add tool, choose a service that recommends OAuth, or choose Custom MCP server and select Sign in with OAuth. For a custom server, enter a connection name and HTTPS MCP endpoint under Connection details. Leave the pre-registered client fields empty unless the server’s documentation gave you a client ID for Formation.
2. Choose Continue to sign in. Formation discovers the server’s authorization server, settles its own client identity, and sends the browser to the server’s sign-in page. Consent there is the server’s, not Formation’s: it decides what the grant may reach (Contentful asks which spaces and environments).
3. The browser returns to the agent’s tools page with the account connected and its supported tools active. Manage tools is optional. Reauthorizing an existing account retains its exclusions and explicit turn-off state.

• Discovery follows the spec: an unauthenticated request for the server’s WWW-Authenticate challenge, RFC 9728 protected resource metadata (from the challenge or the well-known locations), then RFC 8414 or OpenID metadata for the authorization server, in the spec’s order. The authorization server must advertise PKCE (S256) or Formation stops. Every URL involved must be HTTPS and public; redirects are never followed.
• Client identity is chosen in the spec’s priority: pre-registered credentials you entered, then a Client ID Metadata Document when the authorization server supports one (Formation serves its own at PUBLIC_URL/api/mcp/oauth/client; this needs an HTTPS PUBLIC_URL), then RFC 7591 dynamic registration. A server offering none of these needs a pre-registered client ID from its operator.
• The authorization request carries a PKCE challenge, an unguessable state, the RFC 8707 resource (the server’s own identifier from its metadata) and the scopes the server asked for in its challenge, or those its metadata lists. Formation requests nothing beyond that.
• The redirect URI is always PUBLIC_URL/api/mcp/oauth/callback. The callback is single-use and expires ten minutes after the start; it must be completed by the operator account that started it, and when the server says it echoes its issuer (RFC 9207) a mismatch is refused before any code is redeemed.
• Tokens are stored encrypted under MESH_AGENT_MASTER_KEY in the same secrets row a pasted token would use, together with the token endpoint and client identity needed to refresh them. Formation refreshes an access token itself, shortly before it expires or once when the server answers 401, under the connection’s row lock so replicas never spend a single-use refresh token twice. Rotated refresh tokens replace the old one.
• A refused refresh (invalid_grant: the grant was revoked, or the server issued no refresh token and the access token expired) marks the connection with auth_error. Its tools stop being offered without stopping the turn, the dashboard shows the reason, and Reconnect with OAuth starts a new authorization for the same connection. Reauthorizing replaces the credential and preserves tool preferences; renaming keeps them too. Moving an OAuth connection to another endpoint means connecting that endpoint with OAuth: the grant is bound to the resource it was issued for.

​

Identity and execution

​

Upgrading existing connections

​

Cached discovery

• Each agent/account has its own catalog. Sharing an endpoint does not share a credential or the tools visible to that credential.
• Calls open a session and compare the offered definition fingerprint to the live definition before execution. A changed definition is refused for that stale offer, then current definitions can be adopted by a later refresh.
• Credential, endpoint, preference and enablement changes invalidate the old connection version. Old offers cannot execute under the new configuration.
• Temporary refresh failures keep a usable catalog for the unchanged connection; call-time authentication and definition checks still apply. A refused OAuth grant makes the account unavailable until repaired.

​

Knowledge and provenance

​

Supported protocol and resource limits

• Public HTTPS endpoints on port 443, authenticated by an Authorization: Bearer header sent only to the registered URL. Private addresses, redirects, environment proxies, URL credentials and query parameters are refused.
• Up to 256 discovered tools and 16 discovery pages per connection operation. Every supported, non-excluded tool is available for discovery across enabled connections; there is no additional aggregate tool-count or 64 KiB schema selection cap. Progressive tool_search loading controls which definitions enter a model request; loaded definitions still consume its ordinary context budget.
• Input/output schemas up to 32 KiB; descriptions up to 4 KiB; HTTP response streams up to 2 MiB; model-visible results up to 512 KiB. A larger result is truncated to fit, never refused: structured content is dropped first (it usually duplicates the text), then the text’s tail is cut on a rune boundary, and the envelope carries a truncated notice with the total and shown sizes and how to ask for less. The credential check runs on the whole result before the cut.
• Validated inline JSON Schemas, at most 64 levels deep. Schema references and x-mcp-header are unsupported. Unsupported tools are displayed but not selected.
• Text and structured JSON results. Non-text results return errors; resource links and attachments are not fetched.
• A 20-second operation deadline, at most four concurrent provider discoveries, and a 40-second overall discovery budget. Completed catalogs remain available if other servers time out. Local database failures and parent cancellation stop discovery.
• Up to 1,000 tool-source IDs per memory or reply. Combined reply lineage beyond 5,000 sources uses the existing unknown-provenance compaction behavior.

​

Administration API

{
  "version": 7,
  "keep_state": true,
  "tool_classifications": [{
    "name": "save_issue",
    "fingerprint": "<current fingerprint from discovery>",
    "class": "effect",
    "completion_contract": "linear-atomic-append-v1"
  }]
}