Skip to main content
Formation provides one operator API over native tool configuration, MCP accounts, REST API connections, and web infrastructure settings. It follows the identity guardrail. This API is for setup and management; it does not offer tools to the model or replace the execution policy checks.

​
Read an agent’s connections

GET /api/agents/{slug}/connections returns agent_id and connections, including disabled and incomplete connections. Each entry includes:
  • id: the same agent-scoped connection ID used by /integrations.
  • agent_id, name, adapter, and ownership: native/MCP/API acting credentials belong to this agent; web keys are infrastructure with explicit inheritance. Native names are package labels, not verified external account names. Packages without credentials use agent_configuration ownership.
  • revision: a deterministic fingerprint for detecting changes on a subsequent read. It is not a write precondition or a credential-delivery permission.
  • credentials: descriptive references with an agent owner, credential kind, intended audience, presence, and revision. They contain no secret values or database secret IDs. Native API, workspace, and MCP audiences remain separate.
  • actions: supported management actions.
  • Exactly one of native, mcp, api, or web: the adapter’s configuration, enablement, review, health, and version information. Native tools also include their runtime description and class for operation review.
The listing is local and uncached (Cache-Control: no-store); it does not discover remote tools or refresh OAuth. Native package slots exist before configuration; MCP accounts appear after creation; web slots expose disabled, inherit, or own settings. Unpackaged built-in tools have no managed connection here.

​
Create an MCP account

POST /api/agents/{slug}/connections takes adapter: "remote_mcp", auth_kind (bearer or oauth), name, endpoint, and an optional bearer token. OAuth can instead supply pre-registered client_id and client_secret fields. Creation always requests a new independent account, even at an existing endpoint. Bearer creation returns the existing provider_id/enabled response. OAuth returns authorization_url and completes through the existing callback flow. Successful authentication discovers the catalog and enables supported tools automatically. Discovery failures remain visible and retry without erasing the account. Explicit off states and exclusions survive later account edits. Native and web slots are configured through actions rather than created.

​
Create a REST API connection

The same POST route accepts adapter: "http_api", name, base_url, and token. Optional fields are auth_header (default Authorization), auth_prefix (default Bearer; explicitly empty sends the raw token), description, and documentation_url. The response contains a secret-free connection object. Saving does not probe the API. Each enabled connection contributes one generic request tool; API endpoints and named operations are not automatically discovered. See REST API connections.

​
Apply an action

POST /api/agents/{slug}/connections/actions accepts:
The optional target selects a native tool name or secret kind within that connection. It cannot select another package, agent, or infrastructure owner. Removal keeps historical runs and provider metadata used by tool evidence. Other accounts and agents are unaffected. A stale version is rejected; reconnecting requires adding the account again. Removal deletes access from Formation; it does not delete the external account or revoke authorization at the provider. Action audit events include the connection ID, action, and validated native target; credential values and action payloads are not copied into audit details. Action requests apply one existing operation, not a batch transaction. Responses and errors retain that operation’s contract. MCP and web edits still require their stored versions; native edits retain the existing transactional config writes and enablement checks. The listing’s fingerprint does not introduce CAS for legacy native writes. An adapter failure never falls back to another account or infrastructure credential. A malformed or foreign-agent ID is rejected. Instance web defaults remain on the owner-only settings routes. This agent API can select inheritance or an agent override, but cannot modify the instance. There is no instance identity-connection endpoint or shared-account selector.

​
Compatibility and workspace delivery

Native, MCP, and web connections remain projections over their existing stores. REST API connections have their own agent-owned metadata table and encrypted credential references in the existing secret store. Legacy endpoints continue to work; writes through either surface are visible through the other. Disabling or rotating a connection retains the existing runtime revocation and cache behavior. Removing this facade restores the previous API surface without rewriting stored state. Credential references describe ownership and intended audience; they do not authorize sandbox delivery. The workspace resolver separately checks the saved permission, run/agent ownership, credential revision and current authorization before issuing a credential. Permission changes and rotation invalidate active and held sandboxes. See workspace credentials. The capability editor consumes this API. Native API, MCP and workspace credentials remain separate audiences even when they connect to the same vendor.