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

# Connecting an MCP server

> Point an agent at a remote MCP server: transports, credentials, discovery, and diagnosing a provider that won't connect.

<Note>
  This page is about *consuming* someone else's MCP server as a source of
  tools. Sidenet's own MCP server — the one you connect Claude or Cursor to so
  an assistant can manage your organization — is covered under
  [MCP server](/docs/mcp-server).
</Note>

## When to use MCP instead of an API provider

If the vendor already ships an MCP server, use it. Tools and their schemas
arrive over the protocol and stay current without an OpenAPI import or a
re-import when the vendor changes something. Reach for an
[API provider](/docs/connecting-your-api) when there is no MCP server, or when you
want to hand-shape a small set of tools from a large REST surface.

## Adding one

An MCP provider is a tool provider with `type: "mcp"`:

```bash theme={null}
curl -X POST https://api.sidenet.ai/v1/tool-providers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-crm",
    "type": "mcp",
    "base_url": "https://mcp.acme.example/mcp",
    "mcp_transport": "streamable_http",
    "timeout_ms": 10000,
    "auth_type": "bearer",
    "auth_secret": { "token": "…" }
  }'
```

| Field                                     | Notes                                                                                                                                                                                                                             |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_url`                                | Must be `https://`.                                                                                                                                                                                                               |
| `mcp_transport`                           | Required. `streamable_http` (preferred) or `sse` for older servers.                                                                                                                                                               |
| `timeout_ms`                              | 1,000–30,000; defaults to 10,000. At runtime the effective timeout is never below 30 seconds, for both the connection handshake and each call, because remote servers routinely take longer than the protocol's built-in default. |
| `default_headers`                         | Sent on every request; auth headers win on conflict.                                                                                                                                                                              |
| `auth_type`, `auth_config`, `auth_secret` | Same options as any provider — see [Authenticating tool providers](/docs/tool-auth).                                                                                                                                                   |

Do not pass `tools`: they are **discovered** from the server when you save,
prefixed with the provider name (`acme-crm_list_contacts`), and then assigned
to agents like any other tool. Tools whose input schema is not valid JSON
Schema are dropped with a warning rather than allowed to break every request
the agent makes.

<Tip>
  A remote server can expose hundreds of tools. Assign only the ones an agent
  needs; when an agent holds at least one tool from a provider, per-user
  connections to that provider are narrowed to that set, so the agent is never
  offered the full catalogue.
</Tip>

## Credentials

Everything under [Authenticating tool providers](/docs/tool-auth) applies: static
bearer, API key, basic or custom headers; the client-credentials, password and
refresh-token OAuth grants; and per-user credentials supplied at session mint.
The refresh-token grant is the common case for MCP servers fronted by Google
OAuth — sign in once, store the refresh token, and the platform exchanges it
for access tokens without a browser. With an OAuth grant the access token is
injected on every request, so a long-lived connection keeps working across
token rotations.

**Connection reuse.** Per-user connections are cached by provider and a hash
of the credentials for ten minutes, sliding: repeat requests with the same
credentials skip the handshake. Editing the provider evicts its cached
connections, so a change takes effect on the next request rather than when
the cache expires.

**No silent fallback.** If a user's credentials cannot connect, the agent is
not quietly handed the organization's credentials instead. In chat the
provider's tools are replaced for that turn by stubs that tell the model the
provider is unavailable; in workflow runs the step fails.

## When it fails

A provider that cannot connect is **still saved**. The write returns a
`warning` naming the load error, the provider appears with an empty tool
list, and its full configuration is intact, so read the error rather than
deleting and recreating:

```bash theme={null}
curl https://api.sidenet.ai/v1/tool-providers/PROVIDER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "id": "…",
  "type": "mcp",
  "mcp_load_error": "invalid_client (mcp transport error: Could not connect to server …)",
  "last_health_check_at": "2026-09-10T14:02:11Z",
  "last_health_check_ok": false,
  "tools": {}
}
```

`mcp_load_error` is the current in-memory state; the `last_health_check_*`
fields are recorded on every load, successful or not. For OAuth providers the
token exchange is re-run on failure so that the message names the real cause
— a rejected client, an expired refresh token — instead of the protocol's
generic "could not connect with any transport".

Typical causes, in order of frequency:

* **Wrong transport.** An `sse` server addressed as `streamable_http`, or the
  reverse. Check the vendor's documentation for the endpoint path as well.
* **Credential rejected.** A 401 during the handshake. Verify the token or
  grant outside Sidenet first.
* **Slow handshake.** Some servers take longer than 30 seconds to list their
  tools on a cold start; retry once before assuming a fault.

`POST /v1/rebuild-org-tools` reloads every provider and reports per-provider
errors under `mcpErrors`, which is the quickest way to re-check after fixing
something upstream.

## Re-read the schemas after connecting

The parameter names, types and defaults a live server advertises routinely
contradict the vendor's documentation. After the first successful load, open
a few tools and compare their input schema to what you expected. Each
contradiction is either a value to pin in the agent's tool configuration or a
description to tighten — never a prompt rule asking the model to remember the
difference.

## Large MCP toolkits

MCP tools get the same size guard as every other tool, and the same
`loop_responses` capabilities when a server's tools paginate with page-number
or offset parameters. They are never moved behind tool discovery — that
budget applies to connected-app toolkits — so keep the assigned set small at
the agent. See [Working with large APIs](/docs/large-apis).

<Note>
  Approval gating (`require_approval`) applies to MCP tools an agent holds
  through the provider's stored credentials. Tools reached through a per-user
  MCP connection built at request time are not gated yet.
</Note>