MCP server

Why you'd careThe problem it solves

You wrote a Linear integration for your chat app. Then your IDE agent needed the same thing, so you wrote it again against a different tool interface. Then a teammate wanted it in a script and wrote a third. Three implementations of “list my issues”, three places to update when Linear changes an endpoint, three sets of credentials. None of that work was about Linear; it was about the glue between Linear and each client's idea of a tool. MCP exists to make that glue write-once: the integration becomes a process that advertises what it can do, and any compatible client discovers it at connect time. The payoff is not new capability. It is that the second and third client cost nothing.

ConceptWhat it is

The Model Context Protocol defines how a separate process advertises three things — tools, prompts, and resources — and how a client discovers and invokes them. The server is an ordinary program; the client is whatever is holding the conversation. On connect, the client asks what the server offers, receives the tool names, descriptions and schemas, and folds them into the tool list the model sees.

That last step is the one people miss. The model has no notion of MCP. It sees tools. Everything MCP-specific — discovery, transport, reconnection, credentials — happens below the model. Which means the debugging questions are also below the model: did the client connect, did discovery return anything, did the credential attach.

Two deployment shapes matter. In a local client such as a CLI or desktop app, the server is typically a process on your machine that the client launches and talks to directly, and credentials are yours. On Anthropic's server-managed surfaces the server is a remote HTTP endpoint that Anthropic connects to on your behalf; you declare the URL and the credential lives in a vault, keyed by that URL, so it never enters the sandbox.

The boundary against neighbours is clean. MCP is not a capability — it is a distribution channel for capability. A skill can tell the model how to use an MCP-supplied tool well; a plugin can bundle an MCP server alongside skills and commands. None of that changes what the model perceives at the moment of the call.

How it worksThe mechanics

On the Messages API the connector needs both halves, and sending only one is the single most common 400 in this area. You declare the server, and you declare a toolset that references it by name:

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{"type": "url",
                  "url": "https://example.com/mcp",
                  "name": "example-mcp"}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=[...],
)

Every server in mcp_servers must be referenced by exactly one toolset entry; the names must match. The toolset also accepts a default_config and per-tool configs, which is how you build an allowlist rather than exposing everything a server advertises.

The second trap is authentication, and it fails quietly. On Managed Agents the mcp_servers declaration carries no auth field at all — only type, name and URL. Credentials live in a vault and are matched to servers by URL. That match is normalised: scheme and host are lowercased, a default port and a trailing slash are ignored. A different path, a different subdomain, or a non-default port is a different key. When nothing matches, the connection is attempted unauthenticated rather than erroring, so what you observe is a tool that exists and returns permission failures. Related: an invalid credential does not block session creation either — it surfaces later as an error event.

And one category error worth stating plainly: hosted MCP servers generally want OAuth bearer tokens, not the service's own API key. A Notion integration token authenticates against Notion's REST API and will not work as a vault credential for the Notion MCP server. They are different auth systems that happen to belong to the same vendor.

At a glanceSee it

An MCP server's tools become ordinary tools, and credentials attach by URL after the model has already decided to call.

Where it runsSurfaces and availability

The split here is worth internalising: MCP-as-a-standard is portable, MCP-as-a-hosted-connector is not. The protocol travels anywhere you can run a client. What Bedrock and Vertex lack is Anthropic’s server-side connector — the convenience of declaring a URL and having the platform dial it. Losing that costs you a client library and a credential store, not the integration. If your MCP servers are internal and your deployment is a reseller, running the client yourself is the normal answer, not a workaround.

ExampleIn the real world

An engineering org has one MCP server for Linear: six tools, one OAuth app, one deploy. It runs as a remote HTTP endpoint.

Three clients consume it. Developers connect it in their CLI agent, where it is configured once per project and the credential is their own. The support team's Claude-powered triage bot declares it on the Messages API with the paired mcp_servers and mcp_toolset entries. A nightly Managed Agent that files recurring cleanup issues declares the same URL on its Agent object and attaches a vault holding the OAuth credential, which Anthropic refreshes on its own.

When Linear adds a field, one repository changes. Nobody edits the triage bot, nobody edits the agent config, and the developers pick it up on their next connect because discovery happens at connect time.

The failure mode from that same setup is instructive. The nightly agent starts returning “not authorised” on every Linear call while the triage bot is fine. Nothing errored at session creation. The cause was a vault credential registered against the server's bare hostname while the agent declared a URL with a path segment — a different key, no match, and an unauthenticated connection attempted silently.

Not thisWhat it is often confused with

• Not a toolMCP is how tools can arrive, not what they are. An MCP-supplied tool and a hand-declared one are indistinguishable to the model at call time; they differ only in who wrote the schema and how it got into the request.
• Not a skilla skill is text that shapes behaviour, an MCP server is a process that offers capability. They are complements: the useful pairing is a server that exposes six tools and a skill that explains which three matter for your workflow.
• Not a plugina plugin is a packaging and distribution unit that may contain an MCP server along with skills and commands. MCP is the wire protocol underneath one of those parts.
• Not an authentication systemthe protocol carries no credential. On server-managed surfaces auth is a separate object keyed by URL; on local clients it is whatever the process you launched can read.
• Not a way to skip writing an integrationsomeone still implements the Linear calls. MCP means they implement them once instead of once per client.

LimitsWhen not to reach for it

• One client, one integration, no reuse in sight.Declaring the tool directly is fewer moving parts than standing up a server and a discovery path.
• The credential must never leave your infrastructure.Keep the authenticated call host-side behind a custom tool your orchestrator answers, rather than vaulting a secret so a sandbox can be convenient.
• You need instructions, not capability.“Always check the linked issue before closing” is a skill or a tool description. Adding an MCP server will not make the model do it.
• Your target is Bedrock or Vertex.There is no hosted connector; either run an MCP client in your own process or declare the tools directly, and decide that before writing the config.
• The server exposes forty tools and you need four.Attaching the whole toolset floods context. Use the toolset's per-tool config to allowlist, or reach for tool search.

RelatedGo deeper