> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage connections

> Reuse and bind named provider connections without mixing agent identities.

Mesh provides one operator API over native tool configuration, MCP accounts, and
web infrastructure settings. It follows the [identity guardrail](https://github.com/TextureHQ/mesh/blob/main/docs/roadmap.md#agent-owned-acting-identities).
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:

```json theme={null}
{
  "connection_id": "legacy-native/AGENT_UUID/mesh.github",
  "action": "configure",
  "input": {"values": {"default_repository": "TextureHQ/mesh"}}
}
```

The optional `target` selects a native tool name or secret kind within that
connection. It cannot select another package, agent, or infrastructure owner.

| Adapter | Action | Target | Input and result contract |
| - | - | - | - |
| Native | `configure` | Omitted | Existing tool-config `values` request and package response |
| Native | `credential` | Declared, allowlisted secret kind | Existing tool-secret `value` request and presence/hint response |
| Native | `enable`, `disable` | Tool name in this package | Empty input; existing tool state response |
| MCP | `update` | Omitted | Existing versioned account edit and provider response |
| MCP | `discover` | Omitted | Empty input; existing tool review preview response |
| MCP | `enable` | Omitted | Version plus optional `disabled_tools`, `keep_state: true` for preference-only saves, or `keep_preferences: true` to turn on with saved preferences; legacy fingerprints/classes remain accepted |
| MCP | `disable` | Omitted | Empty input; existing disable response |
| MCP | `oauth` | Omitted | Existing OAuth start fields, pinned to this account; no new-account flag |
| Web | `configure` | Omitted | Existing web settings/update and capability-list response |

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](/runtime/workspace-credentials).

The [capability editor](/runtime/capability-setup) consumes this API. Native API,
MCP and workspace credentials remain separate audiences even when they connect
to the same vendor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.