How Claude Connectors Work: Architecture, Lifecycle, and Limits (August 2026)

TL;DR: Claude Connectors are remote MCP servers that Claude reaches through Anthropic’s cloud infrastructure. Claude authenticates, discovers tools and resources, chooses a tool, sends JSON-RPC over Streamable HTTP, and uses the result in the conversation. Interactive connectors add a separate MCP Apps View lifecycle. Claude’s published connector docs still describe an initialize-based 2025-era connection, while core MCP 2026-07-28 is stateless, so support both eras deliberately and test the wire format each Host sends.

If you already know what Claude Connectors are, this post explains what happens under the hood. That matters when a connector works locally but fails in Claude, when a tool is called with the wrong arguments, when an interactive view does not render, or when a production connector times out after working in a small demo.

Claude’s connector system now covers more than “Claude can call my MCP server.” The current Claude connector overview describes connectors as a way to connect Claude to tools, data, and UI through MCP. That means a production connector needs to be designed as a protocol server, an auth boundary, a tool contract, and sometimes an MCP App host surface.

What Changed by August 2026

The connector ecosystem moved quickly after early remote MCP support. A few details are worth updating before we talk about the lifecycle:

• Claude supports Streamable HTTP and legacy HTTP+SSE, with Anthropic deprecating the legacy transport for connectors.
• Core MCP 2026-07-28 removes initialize, initialized, and Mcp-Session-Id, but Claude’s connector docs still describe the older handshake. Do not infer Host support from the latest core release date.
• Claude’s current custom connector docs list separate hosted Claude and Claude Code limits. Hosted Claude surfaces document about 150,000 characters for tool results and a 300 second timeout. Claude Code documents a 25,000 token tool result size, configurable through MAX_MCP_OUTPUT_TOKENS, and a configurable MCP_TOOL_TIMEOUT.
• MCP Apps are now the standard way to describe interactive UI. A tool points to a UI resource with _meta.ui.resourceUri, and hosts render that resource in a sandboxed iframe.
• Claude requires readOnlyHint and destructiveHint in tool metadata. idempotentHint and openWorldHint add useful permission context.
• Custom connectors are available across Free, Pro, Max, Team, and Enterprise plans. Team and Enterprise Owners add the connector for the organization, then members connect their own accounts.
• Custom connectors are reached from Anthropic’s cloud infrastructure. Anthropic publishes 160.79.104.0/21 as its outbound range for connector and OAuth discovery traffic.
• Claude now documents OAuth DCR, Client ID Metadata Documents, Anthropic-held credentials, and fixed request headers in beta. Query-string access tokens remain prohibited.

Those details change how you should design connector tools, not just how you deploy them.

The Architecture and Trust Boundaries

A production Claude Connector has five distinct parts:

Part	Owns	Does not own
Claude client	Conversation UI, connector enablement, user approvals, MCP App container	Your upstream data authorization
Anthropic connector runtime	Remote connection, OAuth tokens for hosted surfaces, MCP requests, result delivery	Your tenant and record-level policy
Remote MCP server	Tool and resource contracts, auth enforcement, request validation, result shaping	Claude’s tool selection or confirmation UI
Upstream service	Source data, business rules, write transactions, rate limits	MCP schemas and Host metadata
MCP App View	Interactive presentation and direct user actions inside the Host	Server credentials or final authorization decisions

For a custom connector, an individual user or an organization Owner registers the remote MCP URL. Each user then connects an account and enables the connector per conversation. Even Claude Desktop and Cowork route remote connector requests through Anthropic’s cloud, so a user’s access to a private network does not make a private endpoint reachable.

The optional View is a second protocol boundary. The Host fetches a ui:// resource and runs it in an isolated iframe on desktop or a native WebView on mobile. The View connects back to the Host with the stable MCP Apps 2026-01-26 handshake. That View-to-Host lifecycle is independent of the core Host-to-server protocol version.

This architecture explains why connector bugs often look unrelated to their cause. A tool schema issue can look like model behavior. A missing WWW-Authenticate header can look like a dead server. A result-size fallback can look like an MCP App hydration bug. Debug the boundaries in order instead of treating the connector as one process.

The Request Lifecycle

Claude’s published connector docs currently describe this production path:

1. Anthropic’s runtime reaches the configured MCP URL. An authless server proceeds; a protected server returns HTTP 401 with a Bearer challenge and protected resource metadata.
2. Claude completes OAuth when required, then sends MCP initialize with clientInfo and a supported 2025-era protocol revision. The server returns its capabilities and identity.
3. Claude requests catalogs such as tools/list and resources/list. Tool descriptions, schemas, annotations, _meta, and server instructions become inputs to Host presentation and model tool selection.
4. The user enables the connector in a conversation and sends a request. Claude decides whether an enabled tool matches the intent and prepares arguments against inputSchema.
5. Claude sends tools/call over Streamable HTTP with the user’s bearer token. The server authenticates the token, authorizes the user and tenant, validates arguments, and calls the upstream service.
6. The server returns content, optional structuredContent, optional _meta, and optional isError. Claude gives model-visible fields to the model and delivers app data to an attached MCP App View.
7. The conversation continues. A follow-up message can cause another model tool call, while a View can call app-visible helper tools through the Host.

Do not gate behavior on an exact Claude clientInfo.name. Anthropic documents several values, including claude-ai, Anthropic with possible suffixes, and claude-code. The value is useful for telemetry and coarse compatibility logging, but any client can claim it, so it cannot authorize a request.

Where MCP 2026-07-28 Fits

The broader MCP 2026-07-28 release changes only the core Host-to-server portion:

2025-era connection	MCP 2026-07-28 connection
Starts with initialize and notifications/initialized	Has no core initialize handshake
Can use Mcp-Session-Id	Has no protocol session ID
Negotiates client identity and capabilities once	Carries version, client identity, and capabilities on each request
May depend on sticky routing	Any request can reach any compatible instance
Uses an open session for server-to-client requests	Uses Multi Round-Trip Requests for supported interactive flows

A modern client can call server/discover to learn supported versions and capabilities, but discovery is optional over HTTP. Modern list and resource results also carry cache hints, and stable catalog ordering helps Hosts keep prompt caches hot.

Claude’s connector documentation does not yet list core 2026-07-28 support, so do not rewrite a working Claude Connector around the new wire format without a compatibility path. Keep workflow state in explicit handles such as jobId, draftId, or cursor now. That design works across both eras and scales without hidden transport sessions.

sunpeak 0.20.x also uses core MCP 2025-11-25 through MCP SDK v1. Its --stateless mode creates a fresh v1 server per request but does not enable the 2026-07-28 wire protocol. Its MCP App View bridge separately uses the stable Apps 2026-01-26 protocol.

Transport: Streamable HTTP

Remote connectors should use Streamable HTTP. The transport is still JSON-RPC, but the server is reached over a single HTTP endpoint, usually something like:

https://api.example.com/mcp

The MCP transport spec defines stdio and Streamable HTTP. For remote connectors, Streamable HTTP is the one that matters. Claude currently supports both Streamable HTTP and legacy HTTP+SSE, but Anthropic is deprecating the legacy transport.

On the 2025-era path Claude documents, the endpoint receives POST requests for JSON-RPC messages and may accept GET for an SSE stream. If you do not offer a server stream, returning 405 Method Not Allowed for GET is valid. An Mcp-Session-Id may identify the initialized transport session.

On a 2026-07-28 request, the same endpoint has different wire requirements. The request is self-contained, MCP-Protocol-Version identifies the protocol revision, and Mcp-Method plus Mcp-Name support header-based routing. There is no session header or core initialization call. A dual-era server must route based on the incoming request instead of assuming every client follows one lifecycle.

The most common production mistakes are ordinary HTTP mistakes:

• The server URL is not publicly reachable from Anthropic’s infrastructure.
• The endpoint requires headers Claude cannot provide.
• The authorization server or protected resource metadata is unreachable from Anthropic’s egress range.
• The server accepts application/json in development but rejects a real request shape in production.
• A proxy buffers or strips streaming responses.
• A platform timeout is shorter than Claude’s tool timeout.
• A modern-only server rejects Claude’s documented initialize path without a downgrade response.

You can keep old HTTP+SSE endpoints if you need older clients, but new Claude Connector work should target Streamable HTTP. If you still have an SSE connector, use the Streamable HTTP migration guide.

Discovery: Capabilities, Tools, and Resources

Discovery is where Claude learns what your connector can do. In Claude’s documented 2025-era path, the server’s initialize response advertises capabilities, then list methods return the current catalogs. In core MCP 2026-07-28, optional server/discover can return supported versions and capabilities before any other request.

Claude currently documents support for tools, prompts, resources, text and image tool results, and text and binary resources. It does not yet document support for resource subscriptions, sampling, or advanced draft capabilities in remote connectors. Feature-detect optional behavior and give core tools a useful text fallback.

A tool definition should include:

• name, the stable programmatic name.
• title, the human-readable display name.
• description, the model-facing description of when and how to use the tool.
• inputSchema, the JSON Schema for arguments.
• outputSchema, when you return structuredContent.
• annotations, such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
• _meta, for host and app metadata such as UI resource links.

Tool descriptions should be specific enough that Claude knows when not to call the tool. “Search tickets by status, owner, and created date” is better than “Search data.” If two tools overlap, make the distinction obvious in the descriptions and schemas.

Return catalogs in deterministic order. Modern MCP results include ttlMs and cacheScope hints, and predictable ordering reduces prompt churn even for Hosts that apply their own caching. Use a private cache scope for user-specific catalogs. A public cache hint on a token-dependent tool list can leak which capabilities one tenant has to another.

For MCP Apps, the current standard pattern is to attach UI metadata to the tool:

{
  name: 'show_ticket_board',
  title: 'Show ticket board',
  description: 'Render a board of support tickets grouped by status.',
  inputSchema: {
    type: 'object',
    properties: {
      teamId: { type: 'string' },
    },
    required: ['teamId'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      tickets: { type: 'array' },
    },
    required: ['tickets'],
  },
  annotations: {
    readOnlyHint: true,
  },
  _meta: {
    ui: {
      resourceUri: 'ui://tickets/board.html',
      visibility: ['model', 'app'],
    },
  },
}

The older ChatGPT-specific _meta["openai/outputTemplate"] key still appears in some Apps SDK examples as a compatibility alias, but _meta.ui.resourceUri is the cross-host shape to use first. Use the MCP Apps SDK helpers when possible because they normalize compatibility metadata for Claude and ChatGPT.

Authentication: OAuth and Identity

Not every connector needs authentication. A connector that serves public data can be authless. For user-specific data, Claude documents these choices:

Mode	Good fit	Important limit
OAuth with DCR	Smaller custom connectors and authorization servers that implement RFC 7591	Registers a fresh client for a new connection
OAuth with CIMD	High-volume connectors with public-client support	Authorization metadata must advertise CIMD and none token endpoint auth
Anthropic-held OAuth credentials	Directory partners with a pre-registered OAuth app	Requires coordination with Anthropic; Claude Code uses its own flow
Static request headers	Organization-wide API key or service credential	Beta; shared by the organization, not per user
No auth	Public, non-user-specific data	Server still needs abuse controls and input validation

A pure machine-to-machine client_credentials grant is not supported for a normal connector connection because Claude requires user consent. Do not put an access token or API key in the connector URL. MCP prohibits access tokens in URI query strings, and URLs routinely leak into logs and proxy telemetry.

Start OAuth with an HTTP 401

Return a transport-level 401, not an MCP tool result with isError: true, when the user must authenticate:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

Claude does not honor that challenge on a 200 response. The protected resource document’s resource value must exactly match the MCP URL the user entered, including its path, and authorization_servers must list the issuer Claude should use first. Both the MCP origin and the authorization server’s discovery endpoints must be reachable from Anthropic’s network.

Claude supports Dynamic Client Registration and Client ID Metadata Documents. CIMD selection requires authorization server metadata with client_id_metadata_document_supported: true and none in token_endpoint_auth_methods_supported. Claude sends S256 PKCE for each authorization request, so advertise and implement code_challenge_methods_supported: ["S256"].

For hosted Claude surfaces, register this redirect URI:

https://claude.ai/api/mcp/auth_callback

Claude Code is different because it is a native client. It uses a loopback redirect on localhost with an ephemeral port. If your connector supports both hosted Claude and Claude Code, handle both redirect patterns in your authorization server.

Claude can refresh reactively after a 401 response and proactively up to five minutes before expiry. Your token endpoint must accept application/x-www-form-urlencoded, return standard OAuth errors such as invalid_grant, and rotate or sender-constrain refresh tokens for public clients. Registration uses JSON, so do not send /register and /token through one body parser without content-type handling.

Keep auth endpoints fast. Claude documents a 10-second wait for discovery, registration, and initial token endpoints, and a 30-second wait for refresh requests. Slow identity infrastructure can make an otherwise healthy MCP endpoint appear unreachable.

OAuth does not replace authorization inside your server. The connector still needs to check:

• Which user owns the OAuth token.
• Which tenant, workspace, repo, project, or account the user can access.
• Whether a tool is read-only or write-capable.
• Whether a write action needs a local approval step in your own system.

Claude can help explain and confirm actions, but your server is the enforcement point.

Tool Results: What the Model Sees and What the UI Gets

The MCP CallToolResult shape is the contract between your server and the host:

return {
  content: [
    {
      type: 'text',
      text: 'Found 12 open tickets for the billing team.',
    },
  ],
  structuredContent: {
    tickets: [
      { id: 'TK-1234', title: 'Invoice failed to load', status: 'open' },
      { id: 'TK-1235', title: 'Card declined incorrectly', status: 'open' },
    ],
  },
  _meta: {
    internalRequestId: 'req_01JZ9...',
  },
};

Use content for unstructured output the model can read. Use structuredContent for JSON that should match your outputSchema. Use _meta for data the component needs but the model should not see. OpenAI’s Apps SDK reference makes the same distinction for ChatGPT Apps: structuredContent and content appear in the transcript, while _meta is delivered only to the component.

That split is useful for privacy and token control. For example, a ticket board can show richer rows in the UI while the model receives a short summary and stable IDs. _meta is hidden from the model, but it still reaches untrusted browser code in the View, so never put access tokens, session cookies, or server credentials there.

Core MCP 2026-07-28 allows broader JSON output shapes, but current Hosts and SDKs may still apply 2025-era object constraints. An object with named fields remains the safest cross-host structuredContent shape. Version your result contract, validate it before returning, and keep the first response small enough to hydrate in every target Host.

For tool-level failures, return a tool result with isError: true when the model can recover:

return {
  isError: true,
  content: [
    {
      type: 'text',
      text: 'The status must be one of open, pending, or closed.',
    },
  ],
};

Reserve protocol-level JSON-RPC errors for protocol failures, missing tools, unsupported methods, malformed requests, and other cases where the host or server cannot complete the MCP operation.

Interactive UI with MCP Apps

Claude Connectors can render interactive UI through MCP Apps. The MCP Apps overview describes the pattern as two MCP primitives working together: a tool declares a UI resource, and a resource returns an interactive HTML interface.

The flow looks like this:

1. Your tool definition includes _meta.ui.resourceUri.
2. The host can preload or fetch that ui:// resource.
3. The resource returns bundled HTML, JavaScript, and CSS.
4. The host renders it inside an isolated iframe on desktop or a native WebView on mobile.
5. The app talks to the host over a JSON-RPC protocol on postMessage.
6. The app can receive tool data, request tool calls, update model context, and respond to host context such as theme, locale, display mode, and container size.

This is different from returning a normal web link. The UI stays in the conversation, it is isolated by the host, and the app can call MCP tools through the host instead of exposing a separate browser API.

The View uses its own stable MCP Apps 2026-01-26 lifecycle. It registers handlers, calls App.connect(), sends ui/initialize, receives Host capabilities and context, then sends ui/notifications/initialized. The core 2026-07-28 removal of Host-to-server initialization does not remove this View handshake.

For connector authors, the important design point is tool visibility. The UI-bearing tool is usually visible to the model and app, while helper tools can be app-only. An app-only helper should not claim the View resource itself:

{
  name: 'page_ticket_board',
  title: 'Page ticket board',
  description: 'Fetch the next page for an already-rendered ticket board.',
  inputSchema: {
    type: 'object',
    properties: {
      cursor: { type: 'string' },
    },
    required: ['cursor'],
  },
  annotations: {
    readOnlyHint: true,
    destructiveHint: false,
  },
  _meta: {
    ui: {
      visibility: ['app'],
    },
  },
}

The model-visible show_ticket_board tool owns resourceUri; the app-only page_ticket_board helper returns data to the View that is already mounted. Keep model-facing tools focused on user intent and app-only tools focused on direct UI mechanics.

Tool Annotations and Permission UX

Tool annotations help Hosts explain and gate tool calls. Claude’s connector docs require each tool to declare readOnlyHint and destructiveHint, and Anthropic’s review guide says read-only tools can receive automatic permission while destructive tools always prompt. The annotations are still not a security boundary.

Use the four core annotations deliberately:

• readOnlyHint: true for tools that only read or compute data.
• destructiveHint: true for tools that may delete or overwrite data.
• idempotentHint: true for tools where repeating the same call has no additional effect.
• openWorldHint: true for tools that contact outside systems, publish content, send messages, or otherwise affect the world outside the user’s local context.

Examples:

{
  name: 'list_tickets',
  annotations: {
    readOnlyHint: true,
    destructiveHint: false,
  },
}

{
  name: 'delete_ticket',
  annotations: {
    readOnlyHint: false,
    destructiveHint: true,
    idempotentHint: true,
    openWorldHint: true,
  },
}

Claude uses these hints for permission UX, but your server still needs to check the OAuth token, user permissions, workspace rules, and tool arguments. Never assume an annotation will stop a bad call, and do not mark a write tool read-only to avoid confirmation.

Limits You Need to Design Around

The old version of this post stated a single 25,000 token limit. That is too broad now.

Claude’s current custom connector docs list these constraints:

• Claude.ai and Claude Desktop max tool result size: about 150,000 characters.
• Claude.ai and Claude Desktop timeout: 300 seconds, or 5 minutes.
• Claude Code max tool result size: 25,000 tokens, configurable with MAX_MCP_OUTPUT_TOKENS.
• Claude Code timeout: configurable with MCP_TOOL_TIMEOUT.

The hosted 150,000-character behavior has an extra MCP App failure mode. When Claude’s code execution sandbox is active, an oversized result can be written to the sandbox filesystem and replaced with a file pointer. A View that expects inline structuredContent then has nothing to hydrate. Keep the initial UI result lean and fetch later pages or detail through app-visible helper tools.

Design to the strictest host you care about. If your connector should work across Claude.ai, Claude Desktop, Claude Code, and other MCP hosts, do not treat the highest limit as your real budget.

Practical patterns:

• Return summaries and IDs from search tools, then fetch full records with detail tools.
• Paginate every collection tool, even if the first version only returns a small dataset.
• Add limit, cursor, sort, and filter fields to schemas before users need them.
• Keep UI-only hydration data in _meta only when the host supports that path.
• Add upstream HTTP timeouts shorter than the host’s timeout.
• Cache repeated reads when the underlying data does not need to be live.
• Make long-running work asynchronous: one tool starts a job, another checks status.

Also implement your own rate limits. Claude does not publish a single connector call rate limit you can design around, and a user can trigger many tool calls in one conversation. Rate limit per user, tenant, connector installation, and upstream service where needed. Return clear recoverable errors so Claude can tell the user what to do next.

Network and Deployment Requirements

Custom connectors are remote MCP servers. Hosted Claude reaches them from Anthropic’s cloud infrastructure, not from the user’s local machine. This is true even when the user is running Claude Desktop or Cowork locally.

That means:

• localhost does not work for a hosted custom connector.
• A private corporate network does not work unless you expose or allowlist access.
• A VPN-only endpoint will fail for most users.
• Anthropic publishes 160.79.104.0/21 for outbound connector, auth discovery, and token traffic.
• Your server needs TLS, stable routing, and production logging.
• If you use OAuth, callback URLs must match the Claude surface using the connector.

Allowlist the published range at both the MCP server and identity provider. A WAF that permits /mcp but blocks /.well-known/*, /register, or /token produces a connector error even when tool traffic would otherwise work.

During development, use a tunnel only for real-host smoke tests. For day-to-day work, use a local inspector so you are not waiting on tunnels, host caches, real account state, or production OAuth setup.

Testing the Full Lifecycle Locally

You should test a Claude Connector at four layers:

1. Protocol tests. Validate the 2025-era initialize path Claude documents, your intended 2026-07-28 behavior or downgrade policy, tools/list, tools/call, resource reads, errors, and auth challenges.

2. Auth and tool contract tests. Exercise protected resource discovery, DCR or CIMD, callbacks, refresh, invalid tokens, tenant isolation, then call each tool with valid, invalid, empty, large, and unauthorized inputs.

3. UI runtime tests. Render MCP Apps in Claude-like and ChatGPT-like host contexts. Test theme, display mode, mobile width, app-only tools, and missing data.

4. Real-host smoke tests. Add the connector to Claude and run a short checklist before release.

sunpeak helps with the tool and UI layers and can connect to any MCP server. The sunpeak inspector replicates ChatGPT and Claude Host runtimes locally, lets you toggle Host, theme, viewport, display mode, tool input, tool result, and simulations, and uses the same inspector runtime for Playwright E2E tests. sunpeak 0.20.x exercises the 2025-era core wire, so use an official modern SDK or conformance tests as a separate gate for core MCP 2026-07-28.

For an existing MCP server:

npx sunpeak inspect --server http://localhost:8000/mcp

For a sunpeak project:

pnpm dev

Use simulation fixtures for repeatable states: empty search results, large lists, OAuth failures, rate limits, destructive action confirmation paths, stale resources, and malformed tool output. Those are the states that break in production because they rarely happen during a happy-path demo.

Production Checklist

Before shipping a Claude Connector, check the full system:

• The server supports Streamable HTTP at one stable MCP endpoint.
• The MCP endpoint and OAuth metadata, registration, and token endpoints are reachable from Anthropic’s 160.79.104.0/21 range.
• The 2025-era initialize path Claude documents passes, and any 2026-07-28 support or downgrade behavior is covered separately.
• tools/list, tools/call, and resource reads pass MCP Inspector checks, with deterministic catalog order.
• Every tool has a narrow description, input schema, output schema when using structuredContent, and correct annotations.
• Every write-capable tool validates user permissions on the server.
• Protected tools return a transport-level 401 with a resource_metadata link, not an isError tool result.
• Protected resource metadata matches the exact MCP URL, and OAuth uses S256 PKCE.
• OAuth redirect URLs cover hosted Claude and Claude Code if you support both.
• Token refresh handles standard OAuth errors and form-encoded token requests.
• Search and list tools paginate.
• Tool results stay below the strictest host limit you support.
• Long-running work has app-level timeouts, upstream request timeouts, and async job fallback.
• MCP Apps declare _meta.ui.resourceUri, CSP domains, and tool visibility deliberately.
• UI-bearing tools own the View resource, while app-only helpers omit resourceUri and stay hidden from the model.
• Error results use isError: true when the model can recover.
• Logs include connector installation, user or tenant ID, request ID, tool name, latency, auth outcome, and result size.
• Local inspector tests and at least one real Claude smoke test pass before release.

The connector itself is only one part of the product surface. The model sees descriptions and schemas. The host sees metadata and auth. The user sees confirmation prompts, UI, and errors. A good connector is designed for all of them.