How to ship your agent as a Claude connector

Anthropic revises the connector submission process and review criteria often. Check the linked docs before you submit.

A Claude connector is a remote MCP server that Claude can authenticate to and call tools on. If your agent already runs as an MCP server, shipping it as a Claude connector takes four steps: make your OAuth flow work with Claude, write tool metadata Claude can reason about, test it as a custom connector, and submit it to Anthropic's Connectors Directory. You can reuse the agent's core implementation, though you may need to narrow or split its exposed tools to meet directory requirements.

Claude supports remote MCP servers as connectors across Claude on the web, Claude Desktop, and the mobile apps, so users can connect your agent once and call its tools from any of them. Claude Code picks up the same connector when it's signed in with a claude.ai subscription. There's no Claude-specific version of the agent to build or maintain.

This is the Claude guide in our series on shipping one agent everywhere. If you followed How to build an agent for your product and serve it everywhere and the ChatGPT plugin guide, most of the work is done; this guide covers only what Claude adds. The end state is the one this series has been working toward: one agent, multiple directories, one codebase.

What is a Claude connector?

A Claude connector is any remote MCP server that Claude can reach over HTTPS, usually authenticating on behalf of each user with OAuth. The Connectors Directory lists ready-made connectors for common tools, and any developer can add their own MCP server as a custom connector or submit it to the directory for public listing.

Because connectors speak standard MCP, Claude sees the same tools any other MCP client does. Claude decides when to call a tool based on its name, description, and annotations, so the metadata you publish is part of the interface.

What you already have from your MCP server (and your ChatGPT listing)

If you already serve your agent over MCP, almost everything carries over unchanged:

• The agent, its instructions, and its business logic
• Tool definitions, schemas, and guardrails
• Your product's data model and permissions
• The remote MCP endpoint itself

If you also shipped the ChatGPT plugin, your OAuth server and tool naming carry over too.

What has to be done specifically for Claude:

• Making your OAuth server work with Claude's flow: client registration through DCR or CIMD, S256 PKCE, and Claude's callback URL
• Tool annotations and descriptions that meet Anthropic's review criteria
• Testing through Claude's custom connector path
• The directory listing and submission

If you haven't exposed your agent over MCP yet, start with How to build an agent for your product and serve it everywhere. That setup isn't repeated here. The four steps below cover what's left.

Step 1: How does authentication work for a Claude connector?

Claude connectors that access individual user accounts use OAuth. Each person signs in and gets a token scoped to their own account, and your server enforces that user's permissions. Claude doesn't support machine-to-machine (client_credentials) grants. It also supports unauthenticated servers for public data and, in a limited organization beta, a shared API key or bearer token that an Owner configures through request headers.

If you've been using Agno service account tokens, you can keep using them with clients like Claude Code, Cursor, or CI. For per-user access through Claude's hosted apps, use OAuth. AgentOS accepts OAuth and service account tokens on the same /mcp endpoint, so adding OAuth doesn't break your existing service-account setups.

The request path is: user → Claude → your MCP server → your product.

Where the connector gets added depends on the plan:

• Free, Pro, and Max: the user adds your server URL themselves. Free accounts are limited to one custom connector.
• Team and Enterprise: an Owner adds the connector for the whole organization, and each member then connects and authenticates individually.

The ChatGPT plugin guide covers how ChatGPT handles the same step.

Reuse your existing OAuth flow

If your product already has OAuth, extend it for Claude rather than adding a second auth system. The AuthKit (WorkOS) setup from How to build an agent for your product and serve it everywhere is the starting point: your MCP server already sends users through AuthKit to sign in, and that flow stays the same.

With AgentOS, pass AuthKit as mcp_auth and set base_url to your server's exact public origin. AgentOS builds your protected resource URL from it (<base_url>/mcp), and you register that URL as a Resource Indicator in the WorkOS dashboard. If you don't use an identity provider, AgentOS can run its own sign-in with AgentOSBuiltinAuth, but everyone who connects shares one secret and the same permissions.

Claude adds a few requirements around how it discovers and talks to your authorization server. You need DCR or CIMD for client registration, S256 PKCE, Claude's callback URL, and a 401 response that advertises your protected resource metadata:

• A way to register Claude as a client. Claude supports Dynamic Client Registration (DCR) and Client ID Metadata Documents (CIMD) out of the box, so in most cases you don't create a client for Claude by hand. Claude uses CIMD when your authorization server metadata advertises "client_id_metadata_document_supported": true and lists "none" in token_endpoint_auth_methods_supported. Otherwise it falls back to DCR, which needs a registration_endpoint. Check which of the two your provider supports.
• S256 PKCE. Claude sends a PKCE challenge on every authorization request, so your authorization server must support S256 and advertise it in code_challenge_methods_supported.
• Claude's callback URL. For Claude on the web, Desktop, and mobile, the redirect URI is https://claude.ai/api/mcp/auth_callback. Claude Code uses a loopback redirect on a random port, so your authorization server must accept localhost and 127.0.0.1 callbacks with any port.
• A 401 that points to your metadata. When a request arrives without a valid token, return a 401 with a WWW-Authenticate header whose resource_metadata parameter points to your protected resource metadata. That's how Claude finds your authorization server. The resource field in that document must match your MCP server URL exactly as users enter it.

If you expect a lot of traffic from the directory, prefer CIMD over DCR. DCR registers a new client on every fresh connection, which can pile up registered clients on your authorization server. If your authorization server supports neither, you can arrange for Anthropic to hold an OAuth client's credentials. Email mcp-review@anthropic.com with the client ID only; Anthropic will explain how to transfer the secret securely. This option covers the hosted Claude apps. Claude Code uses its own OAuth flow, so plan for it separately.

The goal is one identity across surfaces: a user who connects from Claude reaches the same account, permissions, and data they'd get from your product directly or from ChatGPT.

Step 2: How do you make an MCP server discoverable in Claude?

Claude picks tools by reading their names, descriptions, and annotations, so discovery starts with the tool schema. It's also what Anthropic's reviewers check.

• Name each tool for what it does. Tool names must be 64 characters or fewer.
• Describe what the tool does and when to use it. The description must match the tool's actual behavior. If two tools sound interchangeable to a person reading the schema, they'll look interchangeable to the model too.
• Describe the tool; don't instruct Claude. Descriptions that tell Claude how to behave, push it toward other tools, or pull instructions from external sources are rejected as prompt injection.
• Annotate every tool. Each tool needs a title and the applicable hint: readOnlyHint: true for tools that only read, destructiveHint: true for tools that change or delete data. These also set permissions in Claude: read-only tools can run without asking the user each time, and destructive tools always ask.
• Keep reads and writes in separate tools. Anthropic rejects a catch-all tool that accepts both safe and unsafe operations, like an api_request tool with a method parameter. Split reads and writes, and ideally split writes by action (create, update, delete).
• Return useful errors. Generic errors like "Internal Server Error" fail review. Validate inputs and say what went wrong.

The annotation and read/write rules matter most for agents. An agent published as one plain-language tool can usually both read and write, so since Agno 3.0.2, AgentOS publishes each agent tool with destructiveHint: true, readOnlyHint: false, and openWorldHint: true by default. That's the honest description of a tool that can take actions, and it means Claude asks for confirmation before every call.

If most of what users ask is lookups, split the work: publish a read-only agent for questions and keep your full agent for changes. as_tool() sets each tool's name, title, description, and annotations:

agent_os = AgentOS(
    ...,
    mcp=MCPConfig(
        tools=[
            invoice_lookup_agent.as_tool(
                name="lookup_invoices",
                title="Look up invoices",
                description="Answers questions about invoices, balances, and payment status. Send plain language.",
                annotations={"readOnlyHint": True, "destructiveHint": False},
            ),
            invoice_agent.as_tool(
                name="manage_invoices",
                title="Manage invoices",
                description="Creates, updates, and sends invoices. Send plain language.",
            ),
        ],
    ),
)

Only mark a tool read-only if the agent behind it, and every tool that agent can call, only reads.

Directory discovery is the second layer. Someone browsing the Connectors Directory needs to understand what your agent does, why they'd connect it, and what access they're granting. You write the listing's description yourself in the submission portal, and Anthropic doesn't edit it.

Step 3: How do you test a Claude connector before submitting?

Add your server as a custom connector on your own account and use it the way a customer would. You're checking whether someone can use the agent naturally from Claude, which takes more than a successful tool call.

On Free, Pro, or Max: Customize → Connectors → + → Add custom connector, enter your server's public URL, and connect. Enter an OAuth client ID and secret only if your server doesn't support DCR or CIMD. Depending on the version of the dialog, they're under Advanced settings or in a separate OAuth step. You can also validate the auth flow with the MCP Inspector, or add the server to Claude Code with claude mcp add.

Claude connects to your server from Anthropic's cloud, even when you use Claude Desktop, so your server and your authorization server must be reachable over the public internet from Anthropic's IP ranges. A server on localhost, behind a VPN, or inside a private network won't connect as is. If it sits behind a firewall, allowlist Anthropic's IP ranges. For local development, expose it with a tunneling tool like ngrok or Cloudflare Tunnel first. Claude Code is the exception: it connects from your own machine.

Once connected, work through the cases a real user will hit:

• Ask for outcomes without naming the tool, and check that Claude picks the right one
• Connect as users with different permission levels
• Exercise both read and write actions, and check that Claude asks for confirmation on the write tools
• Break things on purpose: expired tokens, failed requests, empty results
• Use the prompts you expect real users to type, not prompts engineered to trigger one function
• Run your longest real tasks: on Claude on the web and Desktop, each tool call times out after 240 seconds, and tool results are capped at about 150,000 characters

Step 4: How do you get listed in the Claude Connectors Directory?

Once the custom connector works end to end, submit it through the submission portal. You need a Pro, Max, Team, or Enterprise plan; Free accounts can't submit. On Team and Enterprise, an Owner submits, and on Enterprise an Owner can give others the Directory permission through a custom role.

Have these ready before you start:

• Your documentation URL (a blog post or help center article is enough, and it must be public by your publish date)
• Your privacy policy URL
• An icon
• Credentials for a test account that's fully populated with realistic data

The portal walks you through connecting your server: its https:// URL and whether every user reaches the same URL. Your tools then sync automatically from the server, grouped as read or write by their annotations. If any tool is flagged for a missing title or annotation, fix it on your server before you submit.

After you submit, your server is scanned automatically and, by default, listed as a community connector. Anthropic may escalate connectors it expects to be especially useful to a verified review, where reviewers test each tool by hand. You don't need to request this. You can track status and reviewer feedback in the submissions dashboard, and escalations go to mcp-review@anthropic.com.

Two kinds of connectors aren't accepted: ones that transfer money or other financial assets, and ones that generate images, video, or audio with AI models.

The same directory serves Claude on the web, Desktop, mobile, and Claude Code. Ranking is based on usage, and every listed connector can be suggested to users in chat when it's relevant to their task, so for most people the listing is the first thing they'll see of your agent. If a submission is rejected, the email lists the checks that failed; fix them and resubmit.

One agent, another surface

You built the agent once, exposed it through MCP, and added what Claude needs to authenticate, understand, test, and distribute it. The tools, instructions, workflows, guardrails, and product logic all stay with the agent; Claude is just another place users can reach it. If you followed the ChatGPT guide too, the same agent is now available in both ecosystems without a second implementation.

One agent. Two directories. One codebase.