native-mcp

name	native-mcp
description	MCP server integration in Claude Code — add servers to .mcp.json, configure transports, and use their tools natively.
version	1.0.0
author	hermes-CCC (ported from Hermes Agent by NousResearch)
license	MIT
metadata	{"hermes":{"tags":["MCP","Tools","Integrations","Configuration","Claude-Code"],"related_skills":["mcporter"]}}

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

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

---

Transport Types

stdio (default — for local processes)

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

HTTP/SSE (for remote or HTTP servers)

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

---

Common MCP Servers

Filesystem

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

Git

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

GitHub

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

Obsidian

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

Playwright (Browser Automation)

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

Notion

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

SQLite

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

---

Prerequisites

npx servers (Node.js)

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

uvx servers (Python)

pip install uv
uvx --version

Python servers

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:

{
  "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

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

All tools from all servers are available simultaneously.