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

# Remote mcp

# Remote MCP tools

**Strategy update (2026-09-18):** The
[tool integration strategy](https://github.com/TextureHQ/mesh/blob/main/docs/runtime/tool-integration-strategy.md) defines the planned shared
catalog, named connections, progressive discovery, and Add capability flow. The
[delivery plan](https://github.com/TextureHQ/mesh/blob/main/docs/roadmap/tool-integration-delivery.md) tracks implementation.
Descriptions of existing behavior below remain the current contract until those
changes ship.

Mesh connects each agent to remote MCP servers over **Streamable HTTP with an
agent-owned credential**: either a bearer token or API key the operator pastes,
or an OAuth grant the operator authorizes in the browser (below, "Connect with
OAuth"). Connections support both read and write tools and are available in
every conversation with that agent, including new conversations. Multiple
servers and multiple accounts at the same endpoint can be connected independently. Existing built-in Linear and GitHub
tools keep their own credentials and enablement.

## Connect a server

1. Open **Agents → your agent → Tools → Remote MCP connections**.
2. Enter a connection name, HTTPS MCP endpoint, and the agent's bearer token or
   API key. The form starts blank. **Use Linear preset** optionally fills in
   `Linear MCP` and `https://mcp.linear.app/mcp`.
3. Choose **Connect**. Mesh 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.

If discovery fails, the account remains saved and the page shows catalog health.
Mesh retries automatically. Connecting requires no extra approval checklist.

Linear's standard endpoint supports reading, creating and editing issues and
comments using a bearer API key or OAuth access token. The token must have the
corresponding permissions in Linear. See [Linear's MCP documentation](https://linear.app/docs/mcp).
Mesh discovers the actual tools and schemas offered to that account; it does not
maintain a vendor-specific tool list.

For an existing connection using `/mcp/readonly`, choose **Edit connection**,
then **Use Linear preset**, and **Save changes**. Leave the token blank to reuse
the saved credential. The expanded catalog is discovered automatically; saved exclusions persist. Endpoint edits
replace only this agent's binding; other agents using the old endpoint keep their
own connections. Named account edits never overwrite a sibling account. Older,
endpoint-based connections retain their collision check when moving to an
endpoint already occupied by another legacy connection.

## Multiple accounts at one endpoint

Each new dashboard connection creates a separate account identity, for both
bearer tokens and OAuth. Give accounts recognizable names, such as “Linear —
Engineering” and “Linear — Support.” Each has its own encrypted credential,
tool preferences, version, tool namespace, and turn-off action. Reauthorizing or rotating
one account does not change another account, even at the same endpoint. Accounts
remain agent-owned; connecting one does not grant another agent access.

API clients opt into this behavior with `new_account: true` on
`POST /api/agents/{slug}/mcp/providers` or
`POST /api/agents/{slug}/mcp/oauth/start`. To update an existing account, use its
returned `provider_id`: the versioned PUT route for bearer edits, or
`provider_id` in OAuth start for reauthorization. OAuth start rejects requests
that specify both `provider_id` and `new_account: true`.

Omitting `new_account` preserves the legacy endpoint-based reconnect slot. It
never selects or overwrites an explicitly created account. Existing connection
IDs, encrypted secret references, tool approvals, historical aliases, and pending
OAuth authorizations survive the migration unchanged. Pending authorizations
created before the upgrade retain legacy reconnect semantics.

The migration replaces the global endpoint uniqueness constraint with uniqueness
for legacy endpoint slots. **Do not run older binaries against the migrated
schema:** their endpoint upsert does not recognize the partial unique index.
Drain old application replicas before applying this migration and starting new
replicas. A rollback to older binaries requires restoring the pre-upgrade database
backup, or explicitly removing/reconciling additional accounts and restoring the
original endpoint constraint. Deleting duplicates automatically would discard
credentials, approvals, or historical provenance and is not a supported rollback.

This is the first implementation slice of the connection-management work. Unified native/web bindings,
named agent-owned connections, and delivery of an agent’s own credentials to its
workspace remain follow-up work. Shared acting accounts and cross-agent identity
grants are prohibited by the [identity guardrail (repository)](https://github.com/TextureHQ/mesh/blob/main/docs/roadmap.md#agent-owned-acting-identities). The MCP cache still keys each binding
by `(agent_id, provider_id)`; distinct accounts therefore remain distinct cache
entries without changing the cache implementation.

## Connect with OAuth

Some servers issue no token to paste. Contentful's hosted MCP server
(`https://mcp.contentful.com/mcp`) is one: it implements the
[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization),
so the only way in is to sign in and consent in a browser. Mesh is the OAuth
client in that flow.

1. In **Remote MCP connections**, choose **Sign in with OAuth** as the
   authentication, or press **Use Contentful preset**. Enter a connection name
   and the HTTPS MCP endpoint. Leave the pre-registered client fields empty
   unless the server's documentation gave you a client ID for Mesh.
2. Choose **Continue to sign in**. Mesh 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 Mesh'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.

What Mesh does on your behalf, and refuses to do:

* **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 Mesh 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)
  when the authorization server supports one (Mesh 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. Mesh 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. Mesh 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.

Mesh never asks for scopes on its own, never sends a token anywhere but the
registered endpoint and its token endpoint, and never surfaces access or
refresh tokens through the API or the dashboard.

## Identity and execution

`tool_providers` describes an endpoint. `agent_tool_providers` binds it to an
agent-owned encrypted secret, connection label, exclusions, optional legacy tool
classifications, and the credential's `auth_kind` (`bearer` or `oauth`). A pending
browser authorization lives encrypted in `mcp_oauth_authorizations` until its
callback consumes it. Sharing an endpoint never shares accounts, catalogs or
permissions between agents. Credentials are never returned by the API.

The access policy is **all supported tools except explicit exclusions**. New tools
are included automatically; changed definitions do not reset the selection.
Exclusions include removed names so a tool that reappears stays off. Credential
rotation and endpoint edits preserve preferences and explicit connection turn-offs.
All changes still fence offers created under an earlier connection version.

Tools use `ClassEffect`/`Effectful` automatically: Mesh records the durable effect
boundary before the call and never replays an uncertain remote operation. The
operator does not have to classify tools. The legacy API still accepts a `query`
classification against an exact fingerprint. An unchanged explicit query keeps
`ClassQuery`/`Replayable`; a changed definition returns to effect semantics. Unknown
classes are refused on submission and interpreted as effects in stored legacy
rows. Server read-only annotations remain hints; they do not authorize replay.

A query classification does not widen where a call may go: every MCP call,
whatever its class, is an outbound request to the registered endpoint and
nowhere else ([R21 (repository)](https://github.com/TextureHQ/mesh/blob/main/docs/roadmap/risks.md#r21) is about query tools that fetch
arbitrary URLs from the key-holding process; a remote MCP tool cannot).

Discovery fingerprints the full advertised definition, including descriptions,
schemas and annotations. Every call verifies that its offered fingerprint still
matches the live definition. Refreshing adopts current definitions automatically;
an in-flight call with an older definition is rejected. Unsupported schemas are
shown in **Manage tools** and omitted from the offer. **Turn off** requires no
network access.

## Upgrading existing connections

Migration `20261002233000_mcp_tool_preferences.sql` converts reviewed subsets to
exclusions using a catalog from the current connection version. If the snapshot
is absent or stale, the old allowlist remains until the first successful discovery
can convert it. Stored classes and credential ownership are retained. Unreviewed
connections left off by the old setup default become active automatically.
Explicit turn-offs are preserved from
stored selections and the latest successful enable/disable audit event. Repeated
boots do not rewrite the migrated policy.

API clients can submit `{ "version": n, "disabled_tools": [] }` to the existing
`enable` route to allow all supported tools, or include the names to exclude.
Use `{ "version": n, "keep_preferences": true }` to turn an account back on
without replacing its preferences, including a legacy subset.
The version-fenced legacy `{ "version": n, "tools": [...] }` request remains
supported and is converted to exclusions. Do not supply both formats.

## Cached discovery

A turn builds its remote tool offer from a stored catalog rather than
contacting every connected server first. Before this, every turn opened a
session per connection and paged `tools/list` before the model saw anything —
a round trip per server on the critical path, under a 40-second budget, to
re-learn a list that changes on the order of releases.

There is nothing to switch on. A connection whose catalog is **not** stored, or
was stored under a different configuration of that connection, is read live for
that turn exactly as it always was, and the result is kept for the next one. So
the cache can only make a turn faster; it can never make an enabled tool
disappear while waiting for a background refresh, which is what would make it a
mode rather than an optimisation.

What is cached is **metadata, never authority**:

* The offer contains the current supported catalog minus the account's exclusions,
  with effect semantics or an unchanged explicit legacy query classification.
* Every call still opens a session and verifies the selected tool's full
  definition against the live server before invoking it. A tool that changed
  since the offer was built is refused at that point whether or not a snapshot
  still lists it. Caching removes a round trip from the offer, not the guard from the call.
* A snapshot belongs to one agent's connection, not to an endpoint and not to a
  provider row. Two agents connected to the same server hold separate catalogs,
  and so do two independent accounts at that server, because each holds its own
  credential and is shown its own tools.

Staleness is decided by the connection version, so a reconnect, a credential
rotation, an endpoint edit, a preference change, or a turn-off invalidates the stored
catalog **immediately and without a network call** — the connection simply
offers nothing until the next refresh, rather than offering something captured
under different permissions. Renewing an OAuth access token is not such a
change: it rewrites the stored credential in place and the catalog survives it.

A catalog is captured automatically on connection, and when an operator discovers or saves preferences, and refreshed
by a background worker roughly every fifteen minutes per connection. Refreshes
are claimed under a lease in a single statement, so every replica can run the
worker and a connection due for refresh is still read once, by one of them, in
batches — replicas cannot compound into a refresh storm.

When a server cannot be reached, its last catalog is **kept and still offered**,
and the connection reports why it is stale along with when it was last read.
Emptying it would silently withdraw enabled tools over a transient outage while
looking like a server that offers nothing. The connection listing carries this
as `catalog`: `health` (`pending`, `ok`, `unavailable`, `unauthorized`), an
operator-facing `detail`, `captured_at`, `failed_at`, `revision`, and `stale`.
Mesh's own fixed sentences fill `detail`; text from the remote server never
does.

`catalog` appears as soon as a connection has been looked at, which includes a
first read that failed — that case reports the failure with no `captured_at`
and `revision` zero, because there is nothing stored behind it yet and the
connection offers nothing. `stale` means a catalog exists but was captured
under a different configuration of the connection, so it too is offering
nothing until the next refresh. A connection no refresh has yet attempted has
no `catalog` at all.

Live discovery has not gone away: it is the fallback, and it is what a cold or
superseded catalog still uses. Only the connections a stored catalog cannot
serve are read, so one newly connected server does not cost the others a round
trip.

Remote write failures can leave an uncertain outcome. Mesh does not automatically
retry effectful calls after a crash or transport failure; an effect tool's
remote failure stops the turn with the effect recorded for recovery. A query
tool's remote failure is an observation the model sees and can recover from
(narrow, retry, or explain). Local persistence failures stop the turn for both.
MCP transport retries remain disabled for both classes; the query class changes
what the turn does with a failure, not how many times the wire is tried.

## Knowledge and provenance

MCP results belong to the agent, without a conversation allowlist or audience
snapshot. Before calling a tool, Mesh validates the persisted call's agent/run
ownership and records provider, remote name and fingerprint in
`tool_source_evidence`. Successful observations retain that evidence in memory
writes and reply provenance. Tool-source leaves carry no conversation restriction;
`public` in this evidence representation means unrestricted across the owning
agent's conversations, not shared credentials or cross-agent memory access.

Ordinary human-message evidence still retains its own privacy rules. A memory
that combines external data with private conversation content retains the
restrictions belonging to that human content. Migration `0056_agent_wide_mcp.sql`
removes the old MCP conversation scopes and updates existing tool-source leaves
in memories and replies without changing human-source leaves.

## 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 offered across all enabled connections;
  there is no additional aggregate tool-count or 64 KiB schema selection cap.
  Definitions still consume the model's 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.

The official Go MCP SDK handles negotiation and Streamable HTTP; its `oauthex`
and `auth` packages parse challenges and metadata and perform dynamic
registration, while Mesh owns the browser round-trip, token storage and
refresh (`internal/tool/mcp/oauth.go`). Local stdio, step-up scope challenges
(`insufficient_scope` at runtime), roots, sampling, elicitation, resources and
prompts are not supported by this connection flow.

## Administration API

Routes require the existing authenticated agent-access authorization and CSRF
boundary, and return `Cache-Control: no-store`.

| Method | Suffix under `/api/agents/{slug}/mcp/providers` | Purpose |
| - | - | - |
| GET | — | Connections and optional Linear preset endpoint. Each connection carries `auth_kind`, any `auth_error`, and `catalog` health once the connection has been looked at |
| POST | — | Save `{name, endpoint, token, new_account?: true}`; `new_account: true` creates an independent account, omission reconnects the legacy endpoint slot; starts disabled |
| PUT | `/{provider}` | Edit `{version, name, endpoint, token?}`; omitted/blank token reuses the saved credential |
| POST | `/{provider}/discover` | Discover the agent's current catalog |
| POST | `/{provider}/enable` | Select `{version, tools: [{name, fingerprint, class}]}`; `class` is `query` or `effect` (omitted → `effect`; anything else → 400) |
| POST | `/{provider}/disable` | Disable without a network call |

OAuth routes. The start is agent-scoped; the callback and client metadata are
install-wide because an authorization server sees one redirect URI and one
client identity per install.

| Method | Path | Purpose |
| - | - | - |
| POST | `/api/agents/{slug}/mcp/oauth/start` | `{name, endpoint, provider_id?, new_account?: true, client_id?, client_secret?}`; returns `{authorization_url}` for the browser. `provider_id` reauthorizes an existing connection; `new_account: true` creates an independent account and is rejected when `provider_id` is provided |
| GET | `/api/mcp/oauth/callback` | The registered redirect URI; session required. Redirects to the agent's tools page with `mcp_oauth=connected&provider=…` or `mcp_oauth=error&reason=…&detail=…` |
| GET | `/api/mcp/oauth/client` | The install's Client ID Metadata Document; public, served only when `PUBLIC_URL` is HTTPS |

Connections list `auth_kind` and, when a grant was refused, `auth_error`. They
also list `catalog` once the connection has been looked at — see "Cached
discovery" above for its fields and for what a stale or unavailable catalog
means.

Migration 0069 adds `mcp_catalog_snapshots`, one row per connection. Its tool
documents are stored in a `json` column rather than `jsonb` on purpose: a
fingerprint is taken over the exact bytes a server advertised, and `jsonb`
stores a parsed structure that it re-renders with sorted keys, so a round trip
through it would change every fingerprint and read as though every reviewed tool
had been modified.

Migration 0055 requires ordinary PostgreSQL and is applied by the normal migration
runner. It drops `conversation_scopes`; older MCP binaries cannot be run against
this schema. The upgrade preserves enabled connections and selected tools, making
them agent-wide. Existing read-only endpoints remain read-only until edited.

Integration tests use real PostgreSQL and local TLS MCP servers. They cover
multiple agents and servers, read/write calls, new conversations, encrypted
credential reuse, stale reviews, revocation, schema validation and provenance.
They do not contact Linear or require production credentials.


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