Skip to main content
Mesh provides one operator API over native tool configuration, MCP accounts, 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 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, or web: the existing 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.

​
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. 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

There is no new account table, credential copy, dual-write, or database migration. The existing stores remain authoritative. 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.