MCP

Connect Claudin to external tools and data as MCP servers — per project, per user, or per machine.

Overview

The Model Context Protocol (MCP) lets Claudin talk to external systems — issue trackers, databases, internal APIs — as servers it connects to over stdio, HTTP, or SSE. Once connected, a server's tools show up to the model as mcp__<server>__<tool>, its prompts as mcp__<server>__<prompt>, and any skills it exposes as <server>:<skill>.

Config scopes

Scope	Where it lives	Shared?
`project`	`.mcp.json` at the project root (walked up from cwd)	Yes — commit it.
`user`	`mcpServers` in the global config, `~/.claudin/config.json`	No — this machine, every project.
`local`	`mcpServers` under this project's entry in `~/.claudin/config.json`	No — this machine, this project only.
`enterprise`	A managed file, exclusive control	Org-wide, blocks `mcp add` while active.

mcpServers is not a field of .claudin/settings.json — that file only holds MCP policy: enabledMcpjsonServers, disabledMcpjsonServers, enableAllProjectMcpServers, and enterprise allowedMcpServers/deniedMcpServers.

See Permissions for how policy keys interact with the rest of Claudin's permission system.

Server config schema

// stdio (default, no "type" needed)
{ "command": "npx", "args": ["my-mcp-server"], "env": { "API_KEY": "xxx" } }

// http
{ "type": "http", "url": "https://mcp.sentry.dev/mcp" }

// sse
{ "type": "sse", "url": "https://example.com/sse", "headers": { "Authorization": "Bearer ..." } }

Example .mcp.json:

{
  "mcpServers": {
    "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
    "my-server": { "command": "npx", "args": ["my-mcp-server"], "env": { "API_KEY": "xxx" } }
  }
}

CLI

Command	What it does
`claudin mcp add <name> <commandOrUrl> [args...]`	Add a server. `-s/--scope local\|user\|project`, `-t/--transport stdio\|sse\|http`, `-e/--env KEY=value`, `-H/--header "K: V"`.
`claudin mcp add-json <name> <json>`	Add a server from a raw JSON string.
`claudin mcp add-from-claude-desktop`	Import servers from a local Claude Desktop config (macOS/WSL).
`claudin mcp remove <name>`	Remove a server. `-s/--scope`.
`claudin mcp list`	List configured servers (health-checks stdio servers — only run this in trusted directories).
`claudin mcp get <name>`	Show detail for one server.
`claudin mcp reset-project-choices`	Reset approved/rejected `.mcp.json` server choices for this project.
`claudin mcp doctor`	Diagnose connection issues.
`claudin mcp serve`	Run Claudin itself as an MCP server.

Inside the REPL, /mcp opens the same management surface — list, enable/disable, or inspect a server's tools without leaving the session.

OAuth

http and sse servers support a full OAuth2 flow. Add auth-time flags when you register the server:

claudin mcp add sentry https://mcp.sentry.dev/mcp \
  --transport http \
  --client-id "..." \
  --client-secret "..." \
  --callback-port 3000

Once a server needs auth, Claudin surfaces it as a pseudo-tool: calling it returns an authorization URL to open, then reconnects and swaps in the server's real tools once the callback completes — no separate login step to remember.

Resources

Two tools read MCP resources directly: one lists what a server exposes, optionally filtered to a single server; the other reads a specific resource by URI. Binary resources are decoded and written to disk — the model gets a file path back, not an inline base64 blob.

Differences from Claude Code

The .mcp.json format and the mcp__server__tool naming convention are the same. What's Claudin-specific: the CLI is claudin mcp instead of claude mcp; the global config lives at ~/.claudin/config.json instead of ~/.claude.json; and there's a fourth scope, local, for machine-and-project-specific servers that shouldn't be committed but also shouldn't apply to every project on the machine.