flyer-crawler.projectium.com/docs/tools/MCP-CONFIGURATION.md

MCP Configuration Guide

This document provides comprehensive guidance for configuring Model Context Protocol (MCP) servers with Claude Code for the Flyer Crawler project.

Table of Contents

1. What is MCP
2. Server Overview
3. Configuration Locations
4. Global Settings Configuration
5. Project-Level Configuration
6. Server Setup Instructions
7. Bugsink MCP
8. PostgreSQL MCP
9. Gitea MCP
10. Other MCP Servers
11. Troubleshooting
12. Best Practices

---

What is MCP

Model Context Protocol (MCP) is a standardized protocol that allows AI assistants like Claude to interact with external tools and services. MCP servers expose capabilities (tools) that Claude can invoke to:

• Query databases
• Manage containers
• Access file systems
• Interact with APIs (Gitea, Bugsink, etc.)
• Store and retrieve knowledge graph data
• Inspect caches and key-value stores

Why We Use MCP:

Benefit	Description
Direct Integration	Claude can directly query databases, inspect containers, and access APIs
Context Awareness	Tools provide real-time information without manual copy-paste
Automation	Complex workflows can be executed through tool chains
Consistency	Standardized interface across different services

---

Server Overview

The Flyer Crawler project uses the following MCP servers:

Server	Tool Prefix	Purpose	Config Location
gitea-projectium	mcp__gitea-projectium__*	Gitea API at gitea.projectium.com	Global
gitea-torbonium	mcp__gitea-torbonium__*	Gitea API at gitea.torbonium.com	Global
podman	mcp__podman__*	Container management	Global
filesystem	mcp__filesystem__*	File system access	Global
memory	mcp__memory__*	Knowledge graph persistence	Global
redis	mcp__redis__*	Redis cache inspection	Global
bugsink	mcp__bugsink__*	Production error tracking (bugsink.projectium.com)	Global
localerrors	mcp__localerrors__*	Dev container error tracking (localhost:8000)	Project
devdb	mcp__devdb__*	Development PostgreSQL database	Project

---

Configuration Locations

Claude Code uses two separate configuration systems for MCP servers:

Global Configuration

Location (Windows):

C:\Users\<username>\.claude\settings.json

Used For:

• Production services (HTTPS endpoints)
• Servers shared across all projects
• Container management (Podman)
• Knowledge graph (Memory)

Project-Level Configuration

Location:

<project-root>/.mcp.json

Used For:

• Localhost services (HTTP endpoints)
• Development databases
• Project-specific tools

When to Use Each

Scenario	Configuration
Production APIs (HTTPS)	Global settings.json
Shared tools (memory, filesystem)	Global settings.json
Localhost services (HTTP)	Project .mcp.json
Development databases	Project .mcp.json
Per-project customization	Project .mcp.json

Important: Localhost MCP servers work more reliably in project-level .mcp.json than in global settings.json. See Troubleshooting for details.

---

Global Settings Configuration

File Format

{
  "mcpServers": {
    "server-name": {
      "command": "path/to/executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "disabled": true
    }
  }
}

Configuration Options:

Field	Required	Description
command	Yes	Path to executable or command
args	No	Array of command-line arguments
env	No	Environment variables for the server
disabled	No	Set to true to disable without removing

Example Global Configuration

{
  "mcpServers": {
    "memory": {
      "command": "D:\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "d:\\nodejs\\node.exe",
      "args": [
        "c:\\Users\\<user>\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
        "d:\\gitea"
      ]
    },
    "podman": {
      "command": "D:\\nodejs\\npx.cmd",
      "args": ["-y", "podman-mcp-server@latest"],
      "env": {
        "DOCKER_HOST": "npipe:////./pipe/podman-machine-default"
      }
    },
    "redis": {
      "command": "D:\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-redis", "redis://localhost:6379"]
    },
    "bugsink": {
      "command": "d:\\nodejs\\node.exe",
      "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
      "env": {
        "BUGSINK_URL": "https://bugsink.projectium.com",
        "BUGSINK_TOKEN": "<40-char-hex-token>"
      }
    },
    "gitea-projectium": {
      "command": "d:\\gitea-mcp\\gitea-mcp.exe",
      "args": ["run", "-t", "stdio"],
      "env": {
        "GITEA_HOST": "https://gitea.projectium.com",
        "GITEA_ACCESS_TOKEN": "<your-token>"
      }
    },
    "gitea-torbonium": {
      "command": "d:\\gitea-mcp\\gitea-mcp.exe",
      "args": ["run", "-t", "stdio"],
      "env": {
        "GITEA_HOST": "https://gitea.torbonium.com",
        "GITEA_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

---

Project-Level Configuration

File Location

Create .mcp.json in the project root:

d:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com\.mcp.json

File Format

{
  "mcpServers": {
    "server-name": {
      "command": "path/to/executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Current Project Configuration

{
  "mcpServers": {
    "localerrors": {
      "command": "d:\\nodejs\\node.exe",
      "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
      "env": {
        "BUGSINK_URL": "http://127.0.0.1:8000",
        "BUGSINK_TOKEN": "<40-char-hex-token>"
      }
    },
    "devdb": {
      "command": "D:\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:postgres@127.0.0.1:5432/flyer_crawler_dev"
      ]
    }
  }
}

---

Server Setup Instructions

Memory (Knowledge Graph)

Package: @modelcontextprotocol/server-memory

Purpose: Persists knowledge across sessions - project context, credentials, known issues.

Configuration:

"memory": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": ["-y", "@modelcontextprotocol/server-memory"]
}

Key Tools:

• mcp__memory__read_graph - Read entire knowledge graph
• mcp__memory__search_nodes - Search for specific entities
• mcp__memory__create_entities - Add new knowledge

Filesystem

Package: @modelcontextprotocol/server-filesystem

Purpose: Provides file system access to specified directories.

Configuration:

"filesystem": {
  "command": "d:\\nodejs\\node.exe",
  "args": [
    "c:\\Users\\<user>\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
    "d:\\gitea"
  ]
}

Note: The last argument(s) specify allowed directories.

Podman/Docker

Package: podman-mcp-server

Purpose: Container management - list, start, stop, inspect containers.

Configuration:

"podman": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": ["-y", "podman-mcp-server@latest"],
  "env": {
    "DOCKER_HOST": "npipe:////./pipe/podman-machine-default"
  }
}

Key Tools:

• mcp__podman__container_list - List running containers
• mcp__podman__container_logs - View container logs
• mcp__podman__container_inspect - Detailed container info
• mcp__podman__image_list - List images

Redis

Package: @modelcontextprotocol/server-redis

Purpose: Inspect Redis cache, set/get values, list keys.

Configuration:

"redis": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": ["-y", "@modelcontextprotocol/server-redis", "redis://localhost:6379"]
}

Key Tools:

• mcp__redis__get - Get value by key
• mcp__redis__set - Set key-value pair
• mcp__redis__list - List keys matching pattern
• mcp__redis__delete - Delete key(s)

---

Bugsink MCP

Bugsink is a self-hosted error tracking service. We run two instances:

Instance	URL	MCP Server	Purpose
Production	https://bugsink.projectium.com	bugsink	Production error tracking
Development	http://localhost:8000	localerrors	Dev container error tracking

Installation

The bugsink-mcp package is NOT published to npm. Clone and build from source:

# Clone the repository
git clone https://github.com/j-shelfwood/bugsink-mcp.git d:\gitea\bugsink-mcp

# Install and build
cd d:\gitea\bugsink-mcp
npm install
npm run build

Repository: https://github.com/j-shelfwood/bugsink-mcp

Configuration

Production (Global settings.json):

"bugsink": {
  "command": "d:\\nodejs\\node.exe",
  "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
  "env": {
    "BUGSINK_URL": "https://bugsink.projectium.com",
    "BUGSINK_TOKEN": "<40-char-hex-token>"
  }
}

Development (Project .mcp.json):

"localerrors": {
  "command": "d:\\nodejs\\node.exe",
  "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
  "env": {
    "BUGSINK_URL": "http://127.0.0.1:8000",
    "BUGSINK_TOKEN": "<40-char-hex-token>"
  }
}

Required Environment Variables:

Variable	Description
BUGSINK_URL	Full URL to Bugsink instance (with protocol)
BUGSINK_TOKEN	40-character hex API token

Important:

• Variable is BUGSINK_TOKEN, NOT BUGSINK_API_TOKEN
• Do NOT use npx - the package is not on npm
• Use http://127.0.0.1:8000 not http://localhost:8000 for localhost

Creating API Tokens

Bugsink 2.0.11 does NOT have a "Settings > API Keys" menu in the UI. Tokens must be created via Django management command.

For Dev Container (localhost:8000):

MSYS_NO_PATHCONV=1 podman exec \
  -e DATABASE_URL=postgresql://bugsink:bugsink_dev_password@postgres:5432/bugsink \
  -e SECRET_KEY=dev-bugsink-secret-key-minimum-50-characters-for-security \
  flyer-crawler-dev sh -c 'cd /opt/bugsink/conf && \
  DJANGO_SETTINGS_MODULE=bugsink_conf \
  PYTHONPATH=/opt/bugsink/conf:/opt/bugsink/lib/python3.10/site-packages \
  /opt/bugsink/bin/python -m django create_auth_token'

For Production (via SSH):

ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"

Both commands output a 40-character lowercase hex token (e.g., a609c2886daa4e1e05f1517074d7779a5fb49056).

Key Tools

• mcp__bugsink__test_connection / mcp__localerrors__test_connection - Verify connection
• mcp__bugsink__list_projects - List all projects
• mcp__bugsink__list_issues - List issues for a project
• mcp__bugsink__get_issue - Get issue details
• mcp__bugsink__get_stacktrace - Get event stacktrace as Markdown

Testing Connection

// Production
mcp__bugsink__test_connection();
// Expected: "Connection successful: Connected successfully. Found N project(s)."

// Development
mcp__localerrors__test_connection();
// Expected: "Connection successful: Connected successfully. Found N project(s)."

---

PostgreSQL MCP

Package: @modelcontextprotocol/server-postgres

Purpose: Execute SQL queries against the development database.

Configuration

Add to project-level .mcp.json:

"devdb": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://postgres:postgres@127.0.0.1:5432/flyer_crawler_dev"
  ]
}

Connection String Format

postgresql://[user]:[password]@[host]:[port]/[database]

Examples:

# Development (local container)
postgresql://postgres:postgres@127.0.0.1:5432/flyer_crawler_dev

# Test database
postgresql://flyer_crawler_test:password@127.0.0.1:5432/flyer_crawler_test

Database Information

Property	Value
Container	flyer-crawler-postgres
Image	postgis/postgis:15-3.4
Host (from Windows)	127.0.0.1
Host (from container)	postgres
Port	5432
Database	flyer_crawler_dev
User	postgres
Password	postgres

Usage Examples

// List all tables
mcp__devdb__query({ sql: "SELECT tablename FROM pg_tables WHERE schemaname = 'public'" });

// Count records
mcp__devdb__query({ sql: 'SELECT COUNT(*) FROM flyers' });

// Check table structure
mcp__devdb__query({
  sql: "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'flyers'",
});

// Find recent records
mcp__devdb__query({
  sql: 'SELECT id, name, created_at FROM flyers ORDER BY created_at DESC LIMIT 10',
});

Prerequisites

1. PostgreSQL container must be running:

   podman ps | grep flyer-crawler-postgres
   

2. Port 5432 must be mapped:

   podman port flyer-crawler-postgres
   # Expected: 5432/tcp -> 0.0.0.0:5432
   

3. Database must exist:

   podman exec flyer-crawler-postgres psql -U postgres -c "\l" | grep flyer_crawler_dev
   

---

Gitea MCP

Binary: gitea-mcp (compiled Go binary)

Purpose: Interact with Gitea repositories, issues, pull requests.

Configuration

"gitea-projectium": {
  "command": "d:\\gitea-mcp\\gitea-mcp.exe",
  "args": ["run", "-t", "stdio"],
  "env": {
    "GITEA_HOST": "https://gitea.projectium.com",
    "GITEA_ACCESS_TOKEN": "<your-token>"
  }
}

Getting Access Token

1. Log in to Gitea web interface
2. Go to Settings > Applications
3. Under Generate New Token, enter a name
4. Select required scopes (typically read:user, write:repository, write:issue)
5. Click Generate Token
6. Copy the token immediately (shown only once)

Key Tools

• mcp__gitea-projectium__list_my_repos - List accessible repositories
• mcp__gitea-projectium__list_repo_issues - List issues in a repo
• mcp__gitea-projectium__get_issue_by_index - Get issue details
• mcp__gitea-projectium__create_issue - Create new issue
• mcp__gitea-projectium__create_pull_request - Create PR
• mcp__gitea-projectium__get_file_content - Read file from repo
• mcp__gitea-projectium__list_branches - List branches

Example Operations

// List repositories
mcp__gitea - projectium__list_my_repos({ page: 1, pageSize: 20 });

// Get issue
mcp__gitea -
  projectium__get_issue_by_index({
    owner: 'username',
    repo: 'repository-name',
    index: 42,
  });

// Create issue
mcp__gitea -
  projectium__create_issue({
    owner: 'username',
    repo: 'repository-name',
    title: 'Bug: Something is broken',
    body: '## Description\n\nSteps to reproduce...',
  });

---

Other MCP Servers

Sequential Thinking

Package: @modelcontextprotocol/server-sequential-thinking

Purpose: Structured step-by-step reasoning for complex problems.

"sequential-thinking": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}

Playwright (Browser Automation)

Package: @anthropics/mcp-server-playwright

Purpose: Browser automation for testing and scraping.

"playwright": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": ["-y", "@anthropics/mcp-server-playwright"]
}

Sentry (Cloud Error Tracking)

Package: @sentry/mcp-server

Purpose: Error tracking for Sentry instances (NOT Bugsink).

"sentry": {
  "command": "D:\\nodejs\\npx.cmd",
  "args": ["-y", "@sentry/mcp-server"],
  "env": {
    "SENTRY_AUTH_TOKEN": "<your-sentry-token>"
  }
}

Note: Bugsink has a different API than Sentry. Use bugsink-mcp for Bugsink instances.

---

Troubleshooting

Localhost Servers Not Loading

Symptoms:

• mcp__localerrors__* or mcp__devdb__* tools not available
• No error messages in logs
• Server silently skipped during startup

Root Cause: Claude Code's global settings.json has issues loading localhost stdio MCP servers on Windows. The exact cause may be related to:

• Multiple servers using the same underlying package
• Localhost URL filtering
• Windows-specific MCP loader bugs

Solution: Use project-level .mcp.json for all localhost MCP servers. This bypasses the global config loader entirely.

Working Pattern:

• Global settings.json: Production HTTPS servers
• Project .mcp.json: Localhost HTTP servers

Server Name Collision

Symptoms:

• Second server with similar name never starts
• No error logged - server silently filtered out

Root Cause: Claude Code may skip MCP servers when names share prefixes (e.g., bugsink and bugsink-dev).

Solution: Use completely distinct names:

• bugsink for production
• localerrors for development (NOT bugsink-dev or devbugsink)

Connection Timed Out

Error: Connection timed out after 30000ms

Causes:

• Server takes too long to start
• npx download is slow
• Server crashes during initialization

Solutions:

1. Move important servers earlier in config
2. Use pre-installed packages instead of npx:

   "command": "d:\\nodejs\\node.exe",
   "args": ["path/to/installed/package/dist/index.js"]
   

3. Check server can start manually

Environment Variable Issues

Common Mistakes:

Wrong	Correct
BUGSINK_API_TOKEN	BUGSINK_TOKEN
http://localhost:8000	http://127.0.0.1:8000

Verification: Test server manually with environment variables:

cd d:\gitea\bugsink-mcp
set BUGSINK_URL=http://127.0.0.1:8000
set BUGSINK_TOKEN=<your-token>
node dist/index.js

Expected output:

Bugsink MCP server started
Connected to: http://127.0.0.1:8000

PostgreSQL Connection Refused

Solutions:

1. Check container is running:

   podman ps | grep flyer-crawler-postgres
   

2. Verify port mapping:

   podman port flyer-crawler-postgres
   

3. Test connection:

   podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT 1"
   

4. Check for port conflicts:

   netstat -an | findstr 5432
   

Verifying Configuration

List loaded servers:

claude mcp list

Check debug logs (Windows):

C:\Users\<username>\.claude\debug\*.txt

Look for MCP server startup messages. Missing servers indicate configuration problems.

---

Best Practices

1. Keep Configs Organized

• Global config: Shared/production servers
• Project config: Local development servers
• Never duplicate the same server in both

2. Order Servers by Importance

Place essential servers first in configuration:

1. memory - Knowledge persistence
2. filesystem - File access
3. podman - Container management
4. Other servers...

3. Use Direct Node Execution

For faster startup, avoid npx and use direct node execution:

// Slow (npx downloads on each start)
"command": "D:\\nodejs\\npx.cmd",
"args": ["-y", "package-name"]

// Fast (pre-installed)
"command": "d:\\nodejs\\node.exe",
"args": ["path/to/installed/dist/index.js"]

4. Disable Instead of Delete

Use "disabled": true to troubleshoot without losing configuration:

"problem-server": {
  "command": "...",
  "disabled": true
}

5. Test Manually First

Before adding to config, verify server works:

cd /path/to/mcp-server
set ENV_VAR=value
node dist/index.js

6. Store Secrets Securely

• Use the memory MCP to store API tokens for future sessions
• Never commit .mcp.json with real tokens (add to .gitignore)
• Use environment variables where possible

7. Restart After Changes

MCP configuration changes require a full VS Code restart (not just window reload).

---

Quick Reference

Available MCP Packages

Server	Package/Source	npm?
memory	@modelcontextprotocol/server-memory	Yes
filesystem	@modelcontextprotocol/server-filesystem	Yes
redis	@modelcontextprotocol/server-redis	Yes
postgres	@modelcontextprotocol/server-postgres	Yes
sequential-thinking	@modelcontextprotocol/server-sequential-thinking	Yes
podman	podman-mcp-server	Yes
gitea	gitea-mcp (binary)	No
bugsink	j-shelfwood/bugsink-mcp	No (build from source)
sentry	@sentry/mcp-server	Yes
playwright	@anthropics/mcp-server-playwright	Yes

Common Tool Prefixes

Server	Tool Prefix	Example
Memory	mcp__memory__	mcp__memory__read_graph
Filesystem	mcp__filesystem__	mcp__filesystem__read_file
Podman	mcp__podman__	mcp__podman__container_list
Redis	mcp__redis__	mcp__redis__get
Bugsink (prod)	mcp__bugsink__	mcp__bugsink__list_issues
Bugsink (dev)	mcp__localerrors__	mcp__localerrors__list_issues
PostgreSQL	mcp__devdb__	mcp__devdb__query
Gitea	mcp__gitea-projectium__	mcp__gitea-projectium__list_my_repos

---

Related Documentation

• CLAUDE.md - MCP Servers Section
• DEV-CONTAINER-BUGSINK.md
• BUGSINK-SYNC.md
• sql/master_schema_rollup.sql

---

Last updated: January 2026