Build an MCP server for Claude changedconnectors/building/index
Nearest release: v2.1.283, published under an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+72added
Lines−48removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
# Build an MCP server for Claude ## Plan your server ### Choose where the server runs ### Choose how users authenticate ### Decide what the server exposes ### Design within the size and timeout limits ### Decide whether to add interactive UI ## Test your server against Claude ## Decide how people get your server ## Related resources ## Next steps # Building custom connectors ## Getting started ### Key resources ## Transport & authentication ### Supported transports ### Authentication features ## Protocol features ### Supported ### Not yet supported ## Technical specifications ## Testing your server ## Related topics
The whole hunk
from line 1, old and new numbered
/
from line 1
1# Building custom connectors
1# Build an MCP server for Claude
22
3> Build your own MCP servers to connect Claude to your tools and data
3> Build a remote MCP server that people use as a connector in Claude: where it runs, authentication, what it exposes, size and timeout limits, and distribution.
44
5## Getting started
5An MCP server gives Claude access to your product or data, and people who use Claude see it as a connector. It's the piece of your [plugin](/docs/build/overview) that reaches your product: the plugin's `.mcp.json` points at the server you build and host, and any skills you include teach Claude how to use it. Claude connects to your server from claude.ai, Claude Desktop, Claude mobile, Cowork, and Claude Code, and the same connector infrastructure backs all of them.
66
7This page is for developers building a remote MCP server for other people to use in Claude. It covers the decisions you make as you build, in the order you meet them, and what Claude's MCP client supports for each one.
8
79<Note>
8 **Authentication is the most common stumbling block.** Before you build, read the [authentication reference](/docs/connectors/building/authentication)—Claude's auth support differs from the generic MCP spec in a few important ways.
10 * If you're new to the protocol itself, see [Model Context Protocol (MCP)](/docs/connectors/building/mcp) for a short orientation
11 * If you want to build a minimal server first and watch Claude call it, see [Build your first MCP server for Claude](/docs/connectors/building/quickstart)
12 * If you're not sure your plugin needs an MCP server, see [Decide what to include in your plugin](/docs/connectors/building/what-to-build)
913</Note>
1014
11Not sure whether to build an MCP server, a plugin, or both? See [what to build](/docs/connectors/building/what-to-build).
15## Plan your server
1216
17Claude implements a subset of the MCP specification, with its own callback URL and its own size and timeout limits.
18
1319<Tip>
14 **Build with Claude.** Install the official [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) in Claude Code—it walks you through building, testing, and packaging an MCP server interactively, using these docs as its reference.
20 To build with Claude's help, install the official [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) in Claude Code. It walks you through building, testing, and packaging an MCP server interactively, using these docs as its reference.
1521</Tip>
1622
17### Key resources
23### Choose where the server runs
1824
19* **SDK Examples**: [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk) and [Python](https://github.com/modelcontextprotocol/python-sdk) SDKs contain server implementation examples
20* **Protocol Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
21* **Hosting Solutions**: Platforms like Cloudflare offer remote MCP server hosting with autoscaling and OAuth management
22* **Auth Specifications**: Review the [authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization) with emphasis on third-party service flows
25A remote server runs on infrastructure you host and is reachable over the internet. Claude connects to it from every Claude app, and a remote server is the recommended kind for a directory listing.
2326
24## Transport & authentication
27A local server runs on the user's computer. To package one for the Claude desktop app, see [Build a desktop extension with MCPB](/docs/connectors/building/mcpb).
2528
26### Supported transports
29A transport is how Claude and your server exchange MCP messages. Use [Streamable HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports/streamable-http), which the MCP specification defines for remote servers. Claude also supports the legacy [HTTP+SSE transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse), which is being deprecated in favor of Streamable HTTP.
2730
28Claude supports both Streamable HTTP and the legacy HTTP+SSE transport. The legacy HTTP+SSE transport is being deprecated in favor of Streamable HTTP.
31### Choose how users authenticate
2932
30### Authentication features
33Decide on authentication before you write tool code. Claude's OAuth client differs from the generic MCP specification in a few places.
3134
32* Supports the [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization), [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), and [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) auth specifications
33* Dynamic Client Registration (DCR) enabled
34* OAuth callback: `https://claude.ai/api/mcp/auth_callback` (hosted surfaces); loopback redirect for Claude Code — see [callback URLs](/docs/connectors/building/authentication#callback-urls)
35* Token refresh and expiry support
36* Custom credentials for non-DCR servers
35Your server can let Claude in with OAuth 2.0, where each user signs in with their own account; with a static credential that an organization Owner enters once and Claude sends as a request header; or with no authentication at all. [Supported authentication types](/docs/connectors/building/authentication#supported-authentication-types) lists each type and which ones you contact Anthropic to use.
3736
38## Protocol features
37If you use OAuth, check these parts of your setup against Claude's client:
3938
40### Supported
39* **Specification version**: Claude follows the [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization), [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), and [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) authorization specifications
40* **Client registration**: Claude can register itself with your authorization server through Dynamic Client Registration (DCR). If your server doesn't support DCR, [Register Claude as an OAuth client](/docs/connectors/building/authentication#register-claude-as-an-oauth-client) lists the other ways to give Claude a client identity
41* **Redirect URI**: allow `https://claude.ai/api/mcp/auth_callback` for the hosted surfaces and a loopback redirect for Claude Code, as [Callback URLs](/docs/connectors/building/authentication#callback-urls) describes
42* **Token refresh**: Claude refreshes access tokens when they expire. [Token refresh](/docs/connectors/building/authentication#token-refresh) has the requirements for your token endpoint
4143
44If you need one of these related flows, follow its page:
45
46* **[Lazy authentication](/docs/connectors/building/lazy-authentication)**: if some of your tools work without the user's account, people can use those right away and sign in only when Claude reaches a tool that needs it
47* **[Enterprise Managed Auth](/docs/connectors/building/enterprise-managed-auth)**: lets enterprise users connect through their organization's SSO without a consent screen
48
49### Decide what the server exposes
50
51Your server can expose these to Claude:
52
4253* [Tools](https://modelcontextprotocol.io/specification/latest/server/tools), [prompts](https://modelcontextprotocol.io/specification/latest/server/prompts), and [resources](https://modelcontextprotocol.io/specification/latest/server/resources)
4354* [Text](https://modelcontextprotocol.io/specification/latest/schema#textcontent) and [image-based](https://modelcontextprotocol.io/specification/latest/server/tools#image-content) tool results
4455* [Text](https://modelcontextprotocol.io/specification/latest/schema#textresourcecontents) and [binary](https://modelcontextprotocol.io/specification/latest/schema#blobresourcecontents) resources
4556
46### Not yet supported
57Claude doesn't yet support these MCP features, so don't build a feature that depends on them:
4758
4859* Resource subscriptions
4960* Sampling
50* Advanced/draft capabilities
61* Advanced or draft capabilities
5162
52## Technical specifications
63If you plan to list the server in the directory, [Design tools that pass review](/docs/connectors/building/review-criteria#design-tools-that-pass-review) covers how to name, describe, and annotate tools.
5364
54| Constraint | Limit |
55| -------------------------------------- | -------------------------------------------------------- |
56| Claude.ai/Desktop max tool result size | \~150,000 characters |
57| Claude Code max tool result size | 25,000 tokens (configurable via `MAX_MCP_OUTPUT_TOKENS`) |
58| Claude Code timeout | Configurable via `MCP_TOOL_TIMEOUT` |
59| Claude.ai/Desktop tool call timeout | 240 seconds (4 minutes) per tool call |
60| Transport protocol | Streamable HTTP (legacy HTTP+SSE being deprecated) |
65### Design within the size and timeout limits
6166
62## Testing your server
67Keep tool results and tool call durations within these limits. They differ between the hosted surfaces and Claude Code.
6368
641. Add directly to Claude via **Customize > Connectors**
652. Use the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector) to validate auth flows
663. Add to Claude Code with `claude mcp add` and check `/mcp` for status. See the [Claude Code MCP quickstart](https://code.claude.com/docs/en/mcp-quickstart).
69| Limit | claude.ai and Desktop | Claude Code |
70| ------------------------ | ------------------------- | -------------------------------------------------------- |
71| Maximum tool result size | \~150,000 characters | 25,000 tokens, configurable with `MAX_MCP_OUTPUT_TOKENS` |
72| Tool call timeout | 240 seconds per tool call | Configurable with `MCP_TOOL_TIMEOUT` |
6773
68## Related topics
74### Decide whether to add interactive UI
6975
70<Columns cols={2}>
71 <Card title="MCP Overview" icon="plug" href="/docs/connectors/building/mcp">
72 Understanding the Model Context Protocol.
73 </Card>
76An MCP App is interactive UI that your MCP server renders inside a Claude conversation, such as an interactive chart or map. It's optional, and you build it as part of the same server. [Get started with MCP Apps](/docs/connectors/building/mcp-apps/getting-started) shows an example and how to build your own.
7477
75 <Card title="Submit to Directory" icon="paper-plane" href="/docs/connectors/building/submission">
76 Review requirements and submit your connector.
77 </Card>
78## Test your server against Claude
7879
79 <Card title="Test in Claude Code" icon="terminal" href="https://code.claude.com/docs/en/mcp">
80 Connect and debug your server with the Claude Code CLI.
81 </Card>
82</Columns>
80You test against the real Claude client, not a staging environment. [Test your connector](/docs/connectors/building/testing) covers adding the server to Claude as a custom connector, validating auth flows with the MCP Inspector, tunneling a local server, and preparing test credentials for review. To connect and debug from the Claude Code command line, see the [Claude Code MCP quickstart](https://code.claude.com/docs/en/mcp-quickstart).
81
82## Decide how people get your server
83
84People add your server to Claude as a connector in one of these ways:
85
86* **As a custom connector**: a user or an organization Owner adds it by entering its URL, with no review by Anthropic
87* **From the directory**: Anthropic lists it in the directory after review, so people find it in Claude. [Publish to the directory](/docs/directory/publish) covers who can submit and what review involves
88* **Inside a plugin**: you bundle the server with the skills that teach Claude to use it, so people install both together. See [Plugin structure and testing](/docs/plugins/build)
89
90Directory and custom connectors run on the same infrastructure. [Directory connectors vs custom connectors](/docs/connectors/building/directory-vs-custom) compares the two and explains when to offer both.
91
92## Related resources
93
94These resources cover the MCP protocol itself rather than Claude's client:
95
96* **SDKs**: the [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk) and [Python](https://github.com/modelcontextprotocol/python-sdk) SDKs contain server implementation examples
97* **Protocol specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
98* **Authorization specification**: read the [authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization), especially the third-party service flows
99* **MCP Inspector**: validate auth flows outside Claude with the [inspector](https://modelcontextprotocol.io/docs/tools/inspector)
100
101## Next steps
102
103* [Authentication for connectors](/docs/connectors/building/authentication): pick an authentication type and meet Claude's OAuth requirements
104* [Test your connector](/docs/connectors/building/testing): add your server as a custom connector and debug connection failures
105* [Plugin structure and testing](/docs/plugins/build): bundle your connector with skills so people install both together
106* [Publish to the directory](/docs/directory/publish): submit your connector for review so people find it in claude.ai on the web, the desktop and mobile apps, and Cowork. Anyone on a paid Claude plan can submit, and on Team and Enterprise an Owner submits
83107
No line in this hunk matches that.