Build your own MCP server and connect it to Claude Code (with `claude mcp add`)

The real connection commands, verified against actual CLI help output.

Building your own MCP server = giving Claude Code a new tool

MCP is the common standard for exposing external tools/data to Claude Code. Official SDKs exist for TypeScript (`@modelcontextprotocol/sdk`) and Python (`mcp`).

Connections are managed via `claude mcp`

Running `claude mcp --help` on this Mac shows real subcommands: `add`, `add-json`, `get`, `list`, `login`, `logout`, `remove`, `reset-project-choices`, `serve`.

Connect a stdio server you built

Pass env vars with `-e` if needed:

$ claude mcp add my-server -e API_KEY=xxx -- npx my-mcp-server

Connect an HTTP server

Use `--transport http`, and `--header` for auth:

$ claude mcp add --transport http my-remote-mcp https://example.com/mcp
$ claude mcp add --transport http my-remote-mcp https://example.com/mcp --header "Authorization: Bearer ..."

Check connection status

`claude mcp list` health-checks registered servers, showing `- ✔ Connected`. Unapproved project-scoped servers show `⏸ Pending approval` until you approve them.

The `.mcp.json` file

Project-scoped MCP connections live here:

{
  "mcpServers": {
    "example": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Scope and safety

`--scope` (local/user/project) controls who shares the connection. Keep permissions minimal, and pass secrets via env vars or a key manager (e.g. KeyDeck), not inline in commands.

FAQ

What SDKs exist for building an MCP server?

Official TypeScript (@modelcontextprotocol/sdk) and Python (mcp) SDKs.

How do I connect my own server?

`claude mcp add`, stdio via `-- command` or HTTP via `--transport http`.

How do I check connection status?

`claude mcp list` health-checks all registered servers.

What's in .mcp.json?

Each server entry has a type and either a url (HTTP) or command (stdio).

How should secrets be handled?

Via env vars or a key manager, not inline in commands.

Find MCP configs on the market →Secure MCP keys with KeyDeck →See School →