How to Build a Custom Claude Connector With Remote MCP

To build a custom Claude connector, expose a remote Model Context Protocol server over Streamable HTTP, register a small set of clearly described tools, protect user-specific access with OAuth, deploy it at a stable public HTTPS URL, and add that URL in Claude's connector settings.

The protocol is the easy part. The product work is deciding what Claude should be allowed to do.

Custom connector versus local MCP server

A local MCP server runs on your computer, usually through stdio. It can access local files and processes, but it is tied to that machine.

A custom Claude connector is a remote MCP server. Anthropic's custom connector guide explains that Claude connects from Anthropic's cloud infrastructure, even when you use Claude Desktop or Cowork. The server therefore needs a public endpoint or an approved network path.

Use a remote connector when:

• The capability belongs to a cloud product or API
• You want it on web, mobile, Desktop, Cowork, and Claude Code
• Several users need their own authenticated access
• The server needs centralized logs, deployment, and updates

Use local stdio when the tool needs your filesystem, local database, clipboard, or another machine-only resource.

Design one narrow job

Do not begin with "connect our whole API." Start with one job a user can describe:

Find the current status of an order and explain the next operational action.

That job might require two read tools:

• find_order
• get_order_events

It probably does not require delete_order, generic SQL, or arbitrary HTTP requests.

A good MCP tool has:

• A verb that describes the action
• A description that says when to use it
• A small validated input schema
• A bounded response
• A clear distinction between reading and writing

Tool descriptions are routing instructions for the model. "Calls API" is weak. "Find an order by public order number and return fulfillment status, shipment timestamps, and non-sensitive customer context" is actionable.

Scaffold a remote MCP server

Start a TypeScript service:

mkdir order-connector
cd order-connector
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install -D typescript tsx @types/express

The official MCP TypeScript SDK recommends Streamable HTTP for remote servers.

A tool registration looks like this:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export const server = new McpServer({
  name: "order-connector",
  version: "1.0.0",
});

server.registerTool(
  "find_order",
  {
    description:
      "Find one order by its public order number and return status and shipment dates.",
    inputSchema: {
      orderNumber: z.string().min(3).max(64),
    },
  },
  async ({ orderNumber }) => {
    const order = await findOrderForAuthorizedUser(orderNumber);

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            orderNumber: order.number,
            status: order.status,
            shippedAt: order.shippedAt,
          }),
        },
      ],
    };
  },
);

The important function is findOrderForAuthorizedUser. Authorization belongs inside the server boundary. Do not accept a userId from Claude and trust it.

Wire the server to a Streamable HTTP transport using the current SDK example. Keep the MCP route dedicated, usually /mcp, and expose a separate health endpoint:

GET  /health
POST /mcp

Use the SDK's current server example instead of copying transport code from an old tutorial. MCP transport APIs have changed faster than the basic tool registration pattern.

Add authorization before write tools

The current MCP authorization specification is based on OAuth 2.1. For user-specific data, the connector must know who authorized the request and what that identity may access.

The MCP authorization specification requires secure redirect handling, PKCE, HTTPS outside local development, token validation, and audience binding.

Your connector should:

1. Authenticate the human through an authorization server.
2. Receive a token issued for this MCP resource.
3. Validate signature, issuer, expiry, audience, and scopes.
4. Derive the internal user from the validated token.
5. Apply row or resource authorization in every tool.
6. Request fresh confirmation for consequential writes.

Do not pass the connector's inbound token directly to an unrelated downstream API. The MCP security guidance explicitly forbids token passthrough because it breaks audience boundaries and creates confused-deputy risks.

For a first release, make every tool read-only. Add writes one at a time after audit logging and authorization tests exist.

Return less data than the upstream API

An upstream customer record may contain an email, address, internal notes, payment metadata, and dozens of operational fields. A shipping-status tool needs very little of that.

Map the response:

return {
  orderNumber: order.number,
  status: order.status,
  carrier: shipment.carrier,
  trackingState: shipment.state,
  estimatedDelivery: shipment.estimatedDelivery,
};

Do not return raw database objects. A narrow response reduces accidental disclosure, prompt-injection surface, context usage, and coupling to internal schema changes.

Also cap result counts and text lengths. A search tool should return the best 10 records, not an unbounded export.

Test the connector as a protocol client

Test three layers separately:

Domain tests

Call the tool handler with authorized and unauthorized identities. Verify tenant isolation, missing records, input limits, and upstream failures.

Protocol tests

Use an MCP inspector or test client to initialize the session, list tools, call each tool, and validate malformed requests. Confirm that unauthenticated calls fail closed.

Claude tests

Add the deployed URL in Claude:

1. Open Customize, then Connectors.
2. Choose Add custom connector.
3. Enter the public MCP URL.
4. Complete authentication.
5. Enable it in a conversation.

On Team and Enterprise plans, an owner adds the connector for the organization and each user connects their own account. Individual plans can add a custom connector directly. Availability and admin controls can change, so use the current Anthropic connector guide as the source of truth.

Test prompts should include both positive and negative cases:

Find order BTN-1042 and summarize its shipping status.

Delete order BTN-1042.

The second prompt should fail if you intentionally shipped a read-only connector.

Deploy for boring reliability

A production connector needs:

• A stable HTTPS endpoint
• Health checks
• Request timeouts
• Structured logs without secrets
• Per-user rate limits
• Retry rules only for safe operations
• Idempotency keys for writes
• Versioned tool behavior
• Alerts for authentication and upstream failures

Claude can call tools repeatedly while solving a multi-step task. A connector that works once but has no limits can turn an ordinary conversation into an upstream incident.

Keep tool names stable. If you need to change a schema incompatibly, add a new tool version, migrate clients, then remove the old one.

A connector launch checklist

• The connector solves one named user job
• Every tool has a narrow description and validated schema
• Read and write tools are visibly distinct
• The authenticated identity comes from a validated token
• Every resource access is authorized server-side
• Responses omit unnecessary customer and internal data
• Result counts and payload sizes are bounded
• Logs record tool, user, outcome, and latency without recording secrets
• Timeouts and rate limits are enforced
• Negative authorization tests pass
• The deployed /mcp endpoint works from outside the private network
• Claude lists the expected tools and no others

Custom Claude connector FAQs

Can a free Claude account use a custom connector?

Anthropic currently documents custom connectors for Free, Pro, Max, Team, and Enterprise, with a one-connector limit for Free users. Treat availability as product policy and verify it in the current connector settings.

Can Claude connect directly to localhost?

Not as a remote custom connector. Anthropic's cloud must reach the endpoint. Use a local MCP server for machine-local work or deploy a narrow remote service for cloud access.

Should I expose a generic API request tool?

Usually not. Generic HTTP or SQL tools make authorization, review, and model routing much harder. Expose named business actions with constrained inputs and outputs.

How do I make the connector available in Claude Code?

Remote connectors added to a Claude.ai account can appear in Claude Code when you are authenticated with that Claude.ai subscription. You can also add the HTTP server directly with claude mcp add --transport http.

Does a connector need to be in the directory?

No. A custom connector can be added by URL. Directory publication is a separate distribution and review path.

If you want to design the connector as part of a larger product architecture, Build This Now helps define the tool boundary, identity flow, deployment, and verification before implementation starts.

A good connector does not make every API available to Claude. It makes one valuable job safe, legible, and dependable.

Posted by @speedy_devv