/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.