I've been deep in the Model Context Protocol ecosystem lately while building solutions around AI context management. During that research, I stumbled across something interesting: Claude Code can run as an MCP server itself. Wait, so Claude Code can both consume MCP servers AND be one? That caught my attention.

The idea of "agent orchestration" - AI tools calling other AI tools - seemed worth exploring. Is this genuinely useful, or just a neat technical trick? I spent the last week figuring it out, hitting every gotcha along the way. Here's what I learned.

Understanding the Capability

Claude Code normally runs in your terminal - you type claude and get an interactive session for coding tasks. But it has a second mode: claude mcp serve. This exposes Claude Code's file editing and command execution tools via the MCP protocol.

What this means: other MCP clients (Claude Desktop, Cursor, Windsurf) can now invoke Claude Code remotely. Instead of you talking to Claude Code directly, other AI tools can delegate work to it.

The dual nature is what makes this interesting. Claude Code can simultaneously:

• Act as an MCP server: Exposing its tools (Bash, Read, Write, Edit, LS, GrepTool, GlobTool, Replace)
• Act as an MCP client: Consuming other MCP servers you've configured

Both work at the same time. You can run claude mcp serve to expose Claude Code while Claude Code itself connects to GitHub and Postgres MCP servers. It's agents all the way down.

This layered architecture matters if you're building anything in the MCP ecosystem. Understanding how tools can compose and delegate to each other opens up different design patterns.

How It Actually Works

Starting Claude Code as an MCP server is straightforward once you know the command:

claude mcp serve

Claude Code runs headless, listening for client connections via stdio transport (standard input/output). There's no network exposure, no authentication needed - security comes through process isolation. Only processes that launch the server can connect to it.

What gets exposed as MCP tools:

• Bash - Execute shell commands
• Read/View - Read file contents
• Write/Edit - Modify files
• LS - List directory contents
• GrepTool - Search file contents
• GlobTool - Find files by pattern
• Replace - Find and replace operations
• dispatch_agent - Delegate to sub-agents

What doesn't get exposed: any MCP servers that Claude Code itself has configured. This is important - there's no MCP passthrough. If Claude Code connects to a GitHub MCP server, clients connecting to Claude Code can't use those GitHub tools directly. Each layer is separate.

The transport mechanism uses JSON-RPC 2.0 over stdio. Client launches the server process, communication happens via process pipes. One process per client connection, no shared state between clients. Each invocation is a fresh Claude Code instance.

Setting It Up

Getting this working requires some specific setup steps. I'll walk through what actually matters.

Prerequisites:

# Node.js 20+
nvm install node
nvm use node

# Claude Code globally
npm install -g @anthropic-ai/claude-code

# Critical first step
claude --dangerously-skip-permissions

That last command is essential. Before Claude Code works as an MCP server, you must run it once with permission acceptance. The --dangerously-skip-permissions flag is necessary because MCP server mode is headless and can't prompt for permissions interactively. Follow the browser authentication, log in, accept terms. One-time requirement.

On macOS, you'll get folder access permission prompts on first run. The first run will likely fail - that's expected behaviour. Grant permissions and subsequent runs work fine.

If you hit "command not found: claude" after installation:

# Check where npm installs global packages
npm config get prefix

# Add to PATH
export PATH="$(npm config get prefix)/bin:$PATH"

Claude Desktop configuration:

Location depends on your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

The configuration:

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

After saving, completely quit Claude Desktop (not just close the window) and restart. Look for the tools icon (hammer) in the interface. Claude Code tools should appear in the list.

Testing it works: "Can you list the files in my home directory using the available tools?" If configured correctly, Claude Desktop invokes Claude Code's LS tool and returns your directory listing.

What This Enables

The use cases cluster around a few patterns I've found interesting.

Delegating complex operations:

Cursor struggles with large refactors. When you hit those limits, you can prompt explicitly: "Use claude code to refactor this component." Cursor delegates to Claude Code via MCP. Claude Code handles the mechanical complexity, results return to Cursor for review.

This makes sense if you regularly work on codebases where Cursor gets stuck. For projects where the inline editing works fine, adding this layer creates unnecessary complexity.

Non-technical users via Claude Desktop:

Someone in Claude Desktop can say: "Set up a React project with TypeScript and Tailwind." Claude Desktop uses Claude Code's Bash tool to execute the commands. No terminal knowledge required, full development setup through natural language.

The interesting part: this bridges the gap between conversational AI and system-level operations without the user needing to understand what's happening underneath.

Agent orchestration patterns:

Claude Desktop → Claude Code → GitHub MCP → GitHub API. Each layer specialises. The pattern matters if you're building systems where different tools have different strengths.

There's a real case study from the community worth noting. A developer built a complete invoice management platform in one day using this orchestration approach. Stack included Claude Code for file operations, GitHub MCP for version control, Postgres MCP for database operations, and Figma MCP for design assets. Features implemented: authentication with magic links, client management, multiple invoice templates, PDF generation, email sending, dashboard with revenue tracking. Cost: $3.65 total for 5.8M tokens. Timeline: one day instead of the usual 2-3 weeks.

The example shows what's possible when you compose specialised capabilities through MCP rather than trying to do everything with a single tool.

For my own work around context management, understanding these composition patterns matters. Different tools excel at different aspects - file operations, API access, database queries. MCP enables that specialisation without forcing everything through a single interface.

Configuration for Different Tools

Beyond Claude Desktop, you can connect Claude Code to other development environments.

Cursor configuration:

Location: ~/.cursor/mcp.json

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

Via Cursor UI: Settings → Tools & Integrations → New MCP Server. This opens the JSON file where you add the configuration above.

Usage pattern: explicitly tell Cursor to use Claude Code when delegating. "Use claude code to refactor this component to use React hooks." Without that explicit prompt, Cursor uses its native capabilities.

Windsurf configuration:

Location: ~/.codeium/windsurf/mcp_config.json

Same JSON structure as Cursor. Restart Windsurf after saving.

Multiple instances pattern:

You can run separate Claude Code servers for different projects:

{
  "mcpServers": {
    "claude-code-frontend": {
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {
        "PWD": "/projects/frontend"
      }
    },
    "claude-code-backend": {
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {
        "PWD": "/projects/backend"
      }
    }
  }
}

Each instance maintains separate context and isolated permissions. Useful if you're juggling multiple codebases and want different MCP configurations for each.

Issues I Encountered

Setup has friction. Here's what actually went wrong and how I fixed it.

PATH problems: After installation, claude command didn't work. Root cause: npm global bin directory not in PATH. Fix requires finding where npm installs packages (npm config get prefix) and adding that path to your shell configuration.

macOS permission dialogs: First run hangs with permission requests. This is expected behaviour, not a bug. Grant all folder permissions when prompted. First run will fail, subsequent runs work. Don't abort during first run - grant permissions and continue.

JSON configuration errors: Server not loading, no error messages. Common mistakes: trailing commas (JSON doesn't allow them), missing quotes around keys/values, unescaped backslashes in Windows paths. Validate JSON syntax before troubleshooting further.

Changes not taking effect: Modified config but behaviour unchanged. Always completely quit the host application (Claude Desktop, Cursor, Windsurf). Close and reopen isn't enough - quit entirely and relaunch.

"Connection closed" errors: Most common cause is Node version conflicts. Use NVM to manage versions explicitly:

nvm install 20
nvm use 20
nvm alias default 20

Windows requires additional consideration - Claude Code needs cmd wrapper for npx commands:

{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@steipete/claude-code-mcp"]
    }
  }
}

Windows requires WSL: Claude Code fundamentally cannot run on native Windows. You need WSL 2 configured with Node.js installed in the Linux environment. This adds complexity and potential performance overhead.

Debugging checklist when tools don't appear:

1. Verify server is running: ps aux | grep "claude mcp serve"
2. Check logs: tail -f ~/Library/Logs/Claude/mcp*.log
3. Test server manually: echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05"},"id":1}' | claude mcp serve
4. Enable debug mode in config: "env": {"MCP_CLAUDE_DEBUG": "true"}
5. Restart client completely

The Community Wrapper Option

There's an enhanced wrapper built by the community at @steipete/claude-code-mcp that provides additional functionality beyond basic claude mcp serve.

What it adds:

• Runs Claude Code in one-shot mode (execute and exit)
• Automatically bypasses permission prompts
• Provides a single unified claude_code tool
• Better handling of complex multi-step operations
• Configurable timeouts
• Debug logging options

Installation via npx:

{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "npx",
      "args": ["-y", "@steipete/claude-code-mcp@latest"]
    }
  }
}

With custom Claude CLI path:

{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "npx",
      "args": ["-y", "@steipete/claude-code-mcp@latest"],
      "env": {
        "CLAUDE_CLI_NAME": "/custom/path/to/claude",
        "MCP_CLAUDE_DEBUG": "false"
      }
    }
  }
}

Use native claude mcp serve for simplicity. Use the wrapper when you need configurable timeouts, debug logging, custom Claude CLI binary locations, or one-shot execution pattern.

My Assessment

After spending time with this setup, here's what I've found.

What works well:

The orchestration concept is genuinely interesting from an architecture perspective. Claude Code does handle complex edits better than inline tools in specific scenarios. The ability to enable non-technical access via Claude Desktop opens up different use cases. Understanding how MCP servers expose capabilities and compose with each other matters for anyone building in this ecosystem.

I've been using Claude Code directly in the terminal for most work - that's where I'm most productive. The MCP server mode becomes relevant when you want other tools to leverage Claude Code's capabilities or when you're exploring how agent orchestration actually works.

What's rough:

Setup complexity is fairly high. First-time configuration could take an hour due to environment conflicts, permission issues, and documentation that's fragmented across GitHub issues and community discussions. Silent failures are frustrating - "Connection closed" errors provide no actionable information without diving into logs.

Windows support is problematic. WSL adds significant complexity with path translation issues, permission mismatches, and performance concerns.

The security model needs consideration. No built-in authentication for remote connections, secrets stored in plaintext configs, no audit trails for tool invocations. Fine for local development, requires additional layers for production use.

Is it worth using?

For experimentation and understanding MCP: Yes. If you're building anything in the MCP ecosystem, understanding these patterns matters. The composition model is how things will evolve.

For regular large refactors: Potentially, if you frequently hit limitations in Cursor or similar tools. For most day-to-day coding where your primary tool works fine: probably overkill.

For enabling non-technical users: Interesting use case that bridges conversational AI and system operations.

What I learned:

How MCP servers expose capabilities through stdio transport. The JSON-RPC protocol implementation details. Agent orchestration patterns where tools delegate to specialised services. Client-server relationships in MCP architecture. These matter when you're building systems that need to compose different AI capabilities.

The bigger picture: MCP ecosystem is growing fast. OpenAI adopted MCP across ChatGPT in March 2025. Google confirmed support for Gemini in April 2025. Block, Apollo, Zed, Replit, Codeium, Sourcegraph all have implementations. "Agents helping agents" is a real pattern emerging, not just hype. Specialisation across tools makes more sense than trying to do everything with one interface.

Practical Reality Check

Here's when this setup makes sense versus when to skip it.

When this makes sense:

You regularly hit limitations in Cursor or Windsurf that Claude Code handles better. Working on large codebases with complex refactors where delegation provides real value. Enabling non-technical stakeholders to perform technical operations through natural language. Exploring MCP capabilities and understanding how agent orchestration works in practice.

For my own work, it's been useful for testing orchestration patterns and understanding MCP composition while building context management solutions. The capability to delegate specialised tasks to appropriate tools matters when you're designing systems that need to coordinate different AI capabilities.

When to skip it:

Small projects where Cursor or Windsurf native capabilities suffice. You don't want to manage the complexity of multiple tools and configurations. Windows user without comfort in WSL. You just want to code without configuring tool chains.

My usage pattern:

I use Claude Code directly in the terminal for most work - that's where I'm most productive. The MCP server mode is relevant for testing orchestration patterns, understanding MCP capabilities, and occasional scenarios where delegation makes sense. Not my daily driver, but a useful capability to understand.

The honest assessment: cool technically, genuinely useful for specific scenarios, setup friction exists, worth exploring if you're deep in the MCP ecosystem.

Technical Notes for MCP Builders

If you're building in the MCP space, some implementation details are worth noting.

The architecture uses JSON-RPC 2.0 over stdio transport. Each client connection spawns a new Claude Code process. No state sharing between connections. Tools get exposed via standard MCP tool format.

Security comes through process isolation - stdio transport means only processes that launch the server can connect. No network exposure, no authentication layer. This works for local development. Remote connections would need OAuth 2.1 wrapper or similar.

Resource usage in MCP server mode: Claude Code normal operation uses 200-500MB memory typically. As MCP server, add 50-100MB overhead. Long-running process that can handle multiple client connections.

Context window management matters. Claude Code maintains conversation context across interactions. Large codebases fill context quickly. Use /clear to reset, /init to rebuild project memory from CLAUDE.md.

For developers building MCP servers, Claude Code's implementation shows patterns for:

• Exposing complex capabilities via MCP protocol
• Tool naming and organisation
• Transport mechanisms (stdio vs HTTP)
• Client-server interactions
• Security through process boundaries

The Model Context Protocol specification is evolving rapidly. Current version is 2025-03-26. Breaking changes happen as the spec matures. Keep this in mind when building systems that depend on MCP.

Conclusion

Claude Code as an MCP server is an interesting capability that emerged while I was researching MCP for context management work. Setup has friction, but once working it demonstrates practical patterns for agent orchestration.

The dual nature - Claude Code as both MCP server and client simultaneously - shows how specialised tools can compose through the protocol. Different tools excel at different tasks. MCP enables that composition without forcing everything through a single interface.

For anyone building in the MCP ecosystem, understanding these patterns matters. How tools expose capabilities. How delegation works across layers. How security boundaries get established. These architectural patterns will become more important as the ecosystem matures.

The practical reality: this isn't revolutionary for day-to-day coding if your current tools work fine. It becomes relevant when you need delegation to specialised capabilities, when you're enabling non-technical users, or when you're building systems that coordinate multiple AI tools.

Worth exploring if you're deep in this space. Worth skipping if you just want to write code without managing tool configurations.

The bigger trend is clear though: AI tools calling other AI tools, each specialising in what it does best, composing through protocols like MCP. That's where things are heading. Claude Code as an MCP server is one practical example of that future.