Chapter 8: Connecting to Claude Code

Claude Code is Anthropic’s CLI for AI-assisted software development. It runs in your terminal and has first-class MCP support. This chapter covers how to configure MCP servers for Claude Code, both at the project level and globally.

Configuration Locations

Claude Code reads MCP configuration from two places:

Project-level configuration takes precedence and is the recommended starting point. It can be committed to version control so all team members share the same server setup.

Project-Level Configuration (.mcp.json)

Create .mcp.json in the root of your project:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["./tools/mcp_server.py"]
    }
  }
}

Unlike Claude Desktop, Claude Code resolves paths relative to the .mcp.json file’s location. Relative paths work here, which makes project configs portable.

With Environment Variables

{
  "mcpServers": {
    "db-tools": {
      "command": "python",
      "args": ["./mcp/db_server.py"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Claude Code supports ${VAR_NAME} syntax to forward environment variables from your shell to the server process.

User-Level Configuration

For servers you want available in every project, add them to ~/.claude/settings.json:

{
  "mcpServers": {
    "personal-notes": {
      "command": "python",
      "args": ["/home/user/tools/notes_server.py"]
    }
  }
}

Use absolute paths in user-level config since the working directory varies by project.

Connecting a Remote Server

For HTTP/SSE servers:

{
  "mcpServers": {
    "remote-tools": {
      "url": "https://my-mcp-server.example.com/sse"
    }
  }
}

Verifying the Connection

Use the /mcp slash command inside Claude Code to see the status of connected servers:

/mcp

This lists all configured servers, their connection status, and the tools they expose. It is the fastest way to confirm your server is connected and working.

You can also use:

/mcp list-tools

To see all available tools from all connected servers.

Permissions and Trust

Claude Code has a permission system that controls what actions Claude can take, including which MCP tool calls require approval.

By default, Claude Code asks for confirmation before calling MCP tools that could have side effects. You can configure trust levels in your settings:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["./server.py"]
    }
  },
  "permissions": {
    "allow": [
      "mcp__my-server__read_file",
      "mcp__my-server__search"
    ]
  }
}

The permission format is mcp__{server-name}__{tool-name}. Tools listed in allow are called without prompting the user.

For local development servers you trust completely, you can allow all tools from a server:

{
  "permissions": {
    "allow": ["mcp__my-server__*"]
  }
}

Using MCP Tools in Conversations

Once connected, Claude Code can use your server’s tools automatically. You do not need to invoke them explicitly — Claude decides when a tool is relevant.

To explicitly ask Claude to use a tool:

Use the search_knowledge_base tool to find documentation about authentication

Claude Code will call the tool and incorporate the result into its response.

Server Logs in Claude Code

When a server is connected via stdio, its stderr output appears in Claude Code’s internal logs. To view logs:

# On macOS/Linux
tail -f ~/.claude/logs/mcp-*.log

Add structured logging to your server to make debugging easier:

import logging, sys
logging.basicConfig(
    stream=sys.stderr,
    level=logging.DEBUG,
    format="%(asctime)s %(name)s %(levelname)s %(message)s",
)

Development Workflow

A typical workflow when developing an MCP server for use with Claude Code:

1. Write and test the server with mcp dev server.py
2. Add it to .mcp.json in your project
3. Run /mcp in Claude Code to verify the connection
4. Test by asking Claude to use the tools
5. Iterate — changes to the server file take effect after restarting Claude Code or the server process

For hot-reload during development, use mcp dev — it watches for file changes and restarts the server automatically.

Key Takeaways

• Use .mcp.json in your project root for project-specific servers
• Use ~/.claude/settings.json for user-wide servers
• Relative paths work in .mcp.json; use absolute paths in user settings
• Use /mcp in Claude Code to verify connections and list tools
• Configure permissions to control which tool calls require user approval
• Server stderr appears in Claude Code’s logs