creating-mcp-servers

Creating MCP Servers

Build and integrate MCP (Model Context Protocol) servers to extend Claude Code with external tools, databases, and APIs.

Quick Reference

What MCP Provides

MCP servers expose three primitives to Claude Code:

Adding MCP Servers

HTTP Transport (Recommended)

# Basic syntax
claude mcp add --transport http <name> <url>

# Example: Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

stdio Transport (Local Servers)

# Basic syntax
claude mcp add --transport stdio <name> -- <command> [args...]

# Example: Database server
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@host:5432/db"

# With environment variables
claude mcp add --transport stdio --env API_KEY=xxx myserver -- npx -y my-package

SSE Transport (Deprecated)

# Use HTTP instead when available
claude mcp add --transport sse asana https://mcp.asana.com/sse

Configuration Scopes

Project Scope Example

claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/

Creates .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Managing Servers

# List all servers
claude mcp list

# Get server details
claude mcp get <name>

# Remove server
claude mcp remove <name>

# Check status in Claude Code
/mcp

# Import from Claude Desktop
claude mcp add-from-claude-desktop

Enable/Disable Servers (2.1.6+)

Use /mcp command to enable or disable servers:

# In Claude Code
/mcp enable <server-name>
/mcp disable <server-name>

Note: As of 2.1.6, @-mentioning MCP servers to enable/disable them is no longer supported. Use /mcp enable <name> instead.

OAuth Authentication

Many cloud MCP servers require OAuth:

1. Add the server: claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. In Claude Code, run: /mcp
3. Select "Authenticate" and complete browser flow
4. Tokens refresh automatically

Environment Variables

In .mcp.json

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Supported syntax:

• ${VAR} - Required variable
• ${VAR:-default} - With default value

Configuration Environment Variables

Using Claude Code as MCP Server

Expose Claude Code tools to other applications:

claude mcp serve

Claude Desktop configuration:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Tool Naming Convention

MCP tools follow the pattern: mcp__<server>__<tool>

Examples:

• mcp__github__search_repositories
• mcp__sentry__get_issues
• mcp__db__query

Wildcard Permissions

{
  "permissions": {
    "allow": ["mcp__github__*"],
    "deny": ["mcp__dangerous__*"]
  }
}

Resources and Prompts

Using Resources (@ mentions)

> Analyze @github:issue://123 and suggest a fix
> Compare @postgres:schema://users with @docs:file://database/user-model

Using Prompts (slash commands)

> /mcp__github__list_prs
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "Bug in login" high

Plugin-Bundled MCP Servers

Plugins can include MCP servers:

// plugin.json
{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Or in .mcp.json at plugin root:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
  }
}

list_changed Notifications (2.1.0+)

MCP servers can dynamically update their tools, prompts, and resources without requiring reconnection. Claude Code automatically handles list_changed notifications.

Enterprise: Managed MCP

Option 1: Exclusive Control

Deploy managed-mcp.json to system directory:

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux/WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

Option 2: Allowlists/Denylists

In managed settings:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

Workflow: Add MCP Server

Prerequisites

• Identify server type (HTTP, stdio, SSE)
• Have authentication credentials ready
• Decide on scope (local, project, user)

Steps

1. Add Server

   • Run appropriate claude mcp add command
   • Include --scope project if team-shared

2. Authenticate (if OAuth)

   • Run /mcp in Claude Code
   • Complete browser authentication flow

3. Test

   • Run /mcp to verify connection
   • Try a simple tool call

Validation

• Server appears in claude mcp list
• /mcp shows "Connected"
• Tools visible in autocomplete

Workflow: Build MCP Server

Prerequisites

• Node.js or Python environment
• MCP SDK installed

Steps

1. Choose SDK

   • TypeScript: npm install @modelcontextprotocol/sdk
   • Python: pip install mcp

2. Implement Server

   • Define tools, resources, or prompts
   • Handle authentication
   • Return structured responses

3. Test Locally

   • Add with stdio transport
   • Verify tools work

4. Deploy (Optional)

   • Host as HTTP endpoint
   • Configure OAuth if needed

See EXAMPLES.md for implementation patterns.

Common Mistakes

Reference Files

External Resources

• MCP Protocol
• MCP SDK Quickstart
• MCP Server Registry
• Claude Code MCP Docs