mcp-integration

name	MCP Integration
description	Set up and use MCP (Model Context Protocol) servers to extend Claude Code capabilities including PRISM semantic memory, filesystem access, and database integration. Use when setting up MCP servers, debugging MCP connections, or understanding MCP tool usage.
allowed-tools	["Read","Bash"]

MCP Integration Skill

What is MCP?

Model Context Protocol (MCP) is a standardized protocol that extends Claude Code with additional capabilities through specialized servers. Each MCP server provides tools that Claude can invoke to interact with external systems, databases, APIs, and services.

Benefits:

• Extends Claude beyond built-in tools (Read, Write, Edit, Grep, Bash)
• Standardized interface for diverse integrations
• Lightweight and composable (mix and match servers)
• Context-efficient (tools described once, invoked many times)

Trade-offs:

• Each server consumes context tokens (typically 1.5-3k per server)
• More tools = more context overhead
• Some operations possible via Bash but MCP provides structure

---

Configuration Architecture

Three Configuration Locations

Config File	Purpose	Key Name	Use Case
~/.claude/mcp_config.json	Custom-built MCPs	servers	Your own MCP servers (PRISM, Orchestration)
~/.config/claude/mcp_config.json	External MCPs	mcpServers	Third-party NPM/Docker MCPs (GitHub, databases)
<project>/.mcp.json	Per-project MCPs	mcpServers	Project-specific tools (MongoDB, Redis for this project)

Key Insight: Two different key names exist (servers vs mcpServers) for historical reasons. Custom MCPs use servers, everything else uses mcpServers.

Configuration Scopes

Claude Code has three scope levels (use local scope for project-specific servers):

Scope	Command	Storage	Visibility	Best For
local (default)	claude mcp add	~/.claude.json	All subdirs in git repo	Project-specific servers (MongoDB for this repo)
project	claude mcp add -s project	.mcp.json	Requires approval settings	Team-shared, checked into git
user	claude mcp add -s user	~/.claude.json	All projects everywhere	Global tools (GitHub, Package Registry)

Recommendation: Use local scope for project databases, user scope for global tools like GitHub.

---

Available MCP Servers (Quick Reference)

Productivity & Documentation

ObsidianPilot MCP - Direct filesystem access to Obsidian vaults

• Full-text search (SQLite FTS5), frontmatter properties, tags, regex
• 100-1000x faster than REST API
• Setup: uvx obsidianpilot with OBSIDIAN_VAULT_PATH env var
• Tools: 15+ tools, ~3k tokens

Jira MCP - Full Jira integration with JQL search

• Search issues, get dev info (commits, PRs)
• Setup: npm install -g @aashari/mcp-server-atlassian-jira
• Tools: 4 tools, ~2.5k tokens

Databases (Configure Per-Project)

MongoDB MCP - Direct MongoDB access

• Find, aggregate, CRUD operations, schema inference
• Setup: claude mcp add mongodb npx -y mongodb-mcp-server -e MDB_MCP_CONNECTION_STRING=...
• Tools: 9 tools, ~3k tokens

PostgreSQL MCP - Query PostgreSQL databases

• SQL queries, schema inspection, read-only by default
• Setup: docker pull mcp/postgres + .mcp.json config
• Tools: 3 tools, ~2.5k tokens

SQLite MCP - Lightweight database operations

• Read/write queries, table management
• Setup: npm install -g @modelcontextprotocol/server-sqlite
• Tools: 6 tools, ~2.5k tokens

Redis MCP - Key operations, cache inspection, pub/sub

• Get/set/delete, TTL management
• Setup: docker pull mcp/redis + .mcp.json config
• Tools: 8 tools, ~2k tokens

Neo4j MCP - Graph database queries

• Cypher queries, graph traversal
• Setup: npm install -g @modelcontextprotocol/server-neo4j
• Tools: 4 tools, ~3k tokens
• Note: You already use Neo4j for PRISM (port 7688)

For detailed setup instructions, see reference.md.

---

Quick Setup Guide

Installing Global External MCPs

Via npm:

npm install -g @modelcontextprotocol/server-github

Add to user scope:

claude mcp add -s user github mcp-server-github \
  -e GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

Verify:

claude mcp list
# Should show: github: mcp-server-github - ✓ Connected

Installing Per-Project MCPs

Use local scope (default - works in all subdirectories):

cd /path/to/your/repo
claude mcp add mongodb npx -y mongodb-mcp-server \
  -e MDB_MCP_CONNECTION_STRING="mongodb://localhost:27017/mydb?authSource=admin"

Verify in subdirectory:

cd /path/to/your/repo/some/deep/subdirectory
claude mcp list
# Should still show mongodb server

Custom MCP Development

Location: ~/repos/claude_mcp/<name>_mcp/

Add to ~/.claude/mcp_config.json:

{
  "servers": {
    "prism": {
      "command": "python3",
      "args": ["-m", "prism_mcp.interfaces.mcp_server"],
      "env": {
        "PYTHONPATH": "~/repos/claude_mcp/prism_mcp",
        "NEO4J_URI": "bolt://localhost:7688",
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6334"
      }
    }
  }
}

Restart Claude Code after config changes.

---

Using MCP Tools

When to Use MCP vs Built-in Tools

Use MCP when:

• Structured API access needed (GitHub issues > parsing gh output)
• Complex queries (MongoDB aggregations > bash mongosh parsing)
• Frequent operations (PRISM memory > manual file management)
• Safety/validation required (Database MCPs prevent SQL injection)

Use built-in Bash when:

• Simple one-off commands
• Tools already available via CLI
• No structured parsing needed
• MCP overhead not justified

Example comparison:

Task	Via Bash	Via MCP	Winner
Create GitHub PR	gh pr create	mcp__github__create_pull_request	MCP (structured, safer)
List files	ls -la	Filesystem MCP	Bash (simpler)
Query MongoDB	mongosh --eval "..."	mcp__mongodb__find	MCP (structured results)
Search packages	npm search foo	mcp__package_registry__search_npm_packages	MCP (detailed info)

Integration Patterns

Pattern 1: Database Queries

Query the MongoDB rthree database for all assets where info.owner.subID = $SUB1

Claude will use mcp__mongodb__find tool automatically.

Pattern 2: Multi-step Workflows

1. Search Jira for open INT tickets assigned to me
2. For each ticket, get dev info (commits, PRs)
3. Summarize work in progress

Claude will chain multiple MCP tools (Jira search → Jira dev info → text summary).

Pattern 3: Memory + Code

Before implementing this feature, check PRISM for similar patterns we've used

Claude will query PRISM MCP, retrieve past decisions, apply patterns to current work.

Pattern 4: Package Research

Find Python packages for PDF parsing, check versions and vulnerabilities

Claude will use Package Registry MCP to search PyPI and get security info.

Best Practices

Do:

• Use specific tool names when you know what you want
• Let Claude choose tools for complex workflows
• Check PRISM before major decisions (if PRISM MCP active)
• Use project-scoped databases (MongoDB, Redis) for per-project work

Don't:

• Install MCPs "just in case" (context overhead adds up)
• Use MCP when Bash is simpler
• Store production secrets in MCP config (use env vars or secrets manager)
• Mix scopes unnecessarily (use local for projects, user for globals)

---

Troubleshooting

Server Not Starting

Symptoms: MCP tools not available after restart, claude mcp list shows "✗ Disconnected"

Quick Fixes:

1. Verify command path:

   which mcp-server-github  # Should return path
   which uvx  # For ObsidianPilot
   

2. Check config syntax:

   python3 -m json.tool ~/.claude/mcp_config.json
   python3 -m json.tool ~/.config/claude/mcp_config.json
   

3. Test server manually:

   python3 -m prism_mcp.interfaces.mcp_server  # Custom MCP
   npx @modelcontextprotocol/server-github     # NPM MCP
   

4. Restart Claude Code - Config changes require full restart (exit and relaunch)

Connection Issues

Database connection failed:

1. Verify service is running:

   mongosh "mongodb://localhost:27017/mydb?authSource=admin"
   redis-cli ping
   psql "postgresql://user:pass@localhost:5432/dbname"
   

2. Check network access:

   nc -zv localhost 27017  # MongoDB
   nc -zv localhost 5432   # PostgreSQL
   nc -zv localhost 6379   # Redis
   

3. Verify credentials - Double-check username, password, database name

GitHub MCP not connecting:

1. Verify token: gh auth status
2. Check token permissions: repo, workflow, read:org scopes
3. Regenerate if expired - Update config with new token

Configuration Errors

"Project MCP servers require approval" (working in subdirectories):

Fix: Remove and re-add with local scope:

claude mcp remove -s project server-name
claude mcp add server-name command -e KEY=value  # Uses local by default

"Too many tools - context budget exceeded":

Fix: Increase token budget in ~/.config/claude/settings.json:

{
  "mcpSettings": {
    "maxToolsTokens": 60000
  }
}

Default: 25k tokens (8-10 servers) Recommended: 60k tokens (20+ servers)

For advanced troubleshooting, see reference.md.

---

Token Budget Management

Planning New MCPs

Before adding an MCP, ask:

1. What value does this provide over existing tools?
2. Can I accomplish this with Bash?
3. How often will I use this?
4. What's the token cost? (check MCP documentation)

Token budget guidelines:

• Small MCPs (1-5 tools): ~1-2k tokens
• Medium MCPs (5-15 tools): ~2-5k tokens
• Large MCPs (15-50 tools): ~5-15k tokens

Calculate headroom:

• Default budget: 200k tokens
• ~50k for tools (25% overhead OK)
• ~150k for actual work

Optimizing Token Usage

Strategies:

1. Per-project MCPs - Only load MongoDB/Redis when working on that project
2. Remove unused MCPs - Uninstall MCPs you added but never use
3. Increase budget - Raise maxToolsTokens to 60k if needed
4. Selective installation - Don't install "nice to have" MCPs

---

Quick Reference Commands

Managing MCPs

# List all configured servers
claude mcp list

# Add server (local scope - recommended for projects)
claude mcp add server-name command -e KEY=value

# Add server (user scope - global tools)
claude mcp add -s user server-name command -e KEY=value

# Remove server
claude mcp remove server-name

# Get server details
claude mcp get server-name

# Test server connection
claude mcp test server-name

Configuration Files

# Custom MCPs (your servers)
cat ~/.claude/mcp_config.json

# External MCPs (third-party)
cat ~/.config/claude/mcp_config.json

# Per-project MCPs
cat .mcp.json  # in project root

# Claude Code settings
cat ~/.config/claude/settings.json

Testing MCP Servers

# Test custom MCP
python3 -m prism_mcp.interfaces.mcp_server

# Test NPM MCP
npx @modelcontextprotocol/server-github

# Test ObsidianPilot
~/.local/bin/uvx obsidianpilot

Debugging

# Validate JSON config
python3 -m json.tool ~/.claude/mcp_config.json

# Check service connectivity
nc -zv localhost 27017  # MongoDB
nc -zv localhost 6379   # Redis

# Test database connection
mongosh "mongodb://localhost:27017/mydb?authSource=admin"
redis-cli ping

# Check logs
tail -f ~/.config/claude/logs/claude-code-*.log

---

Summary

MCP extends Claude Code with specialized tools for databases, APIs, and services.

Key Principles:

1. Evaluate before installing - Token overhead adds up
2. Use local scope for projects - Works in all subdirectories
3. Use user scope for globals - GitHub, Package Registry
4. Test manually first - Verify tools work before configuring MCP
5. Monitor token budget - Check claude mcp list to see tool counts

When to Use This Skill:

• Setting up new MCP servers
• Debugging MCP connection issues
• Understanding which MCP to use for a task
• Troubleshooting configuration problems
• Planning token budget for new MCPs

For detailed server setups and advanced troubleshooting, see reference.md.