Skip to main content
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.

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

​
Credentials

Everything under Authenticating tool providers 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:
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.
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.