Native Mcp

Native MCP Integration

Connect MCP servers to Claude Code and use their tools as first-class native tools.

How It Works

1. Add server config to .mcp.json in your project root
2. Restart Claude Code
3. The server's tools appear as native tools Claude can call directly

.mcp.json Schema

jsonCopy code
{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["path/to/server.py"],
      "env": {
        "API_KEY": "secret"
      }
    }
  }
}

Transport Types

stdio (default — for local processes)

jsonCopy code
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

HTTP/SSE (for remote or HTTP servers)

jsonCopy code
{
  "mcpServers": {
    "remote-server": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Common MCP Servers

Filesystem

jsonCopy code
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Git

jsonCopy code
{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "."]
    }
  }
}

GitHub

jsonCopy code
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."}
    }
  }
}

Obsidian

jsonCopy code
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian"],
      "env": {"OBSIDIAN_VAULT_PATH": "/path/to/vault"}
    }
  }
}

Playwright (Browser Automation)

jsonCopy code
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Notion

jsonCopy code
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/mcp"],
      "env": {"NOTION_API_KEY": "secret_..."}
    }
  }
}

SQLite

jsonCopy code
{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data.db"]
    }
  }
}

Prerequisites

npx servers (Node.js)

bashCopy code
node --version   # must be 18+
npm --version

uvx servers (Python)

bashCopy code
pip install uv
uvx --version

Python servers

bashCopy code
pip install fastmcp mcp

After Adding a Server

1. Save .mcp.json
2. Restart Claude Code (or reload window in IDE extension)
3. Tools from the server now appear in Claude's tool list
4. Test: ask Claude to use one of the new tools

Debugging

Check Claude Code MCP logs:

• Mac/Linux: ~/.claude/logs/
• Windows: %APPDATA%\Claude\logs\

Common issues:

• command not found: install npx/uvx or use full path
• Auth errors: check env section for API keys
• Timeout: server took too long to start

Security Best Practices

Never hardcode secrets in .mcp.json — use env vars from shell:

jsonCopy code
{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Or set in .env and load via direnv / shell profile.

Multiple Servers

jsonCopy code
{
  "mcpServers": {
    "filesystem": {...},
    "github": {...},
    "obsidian": {...},
    "playwright": {...},
    "custom-api": {...}
  }
}

All tools from all servers are available simultaneously.