MCP Setup

How to connect hatch3r's MCP servers and manage secrets securely.

Overview

hatch3r ships with 5 MCP servers enabled by default and 3 opt-in servers. All secrets are centralized in a single .env.mcp file at the project root (gitignored by default). MCP configs use ${env:VAR} placeholders so you never commit secrets.

Where MCP Config Lives

Tool	Config path	When created
Cursor	.cursor/mcp.json	npx hatch3r init (when MCP selected)
Cursor plugin	mcp.json (project root)	Plugin install
Claude Code	.mcp.json	npx hatch3r init
Copilot / VS Code	.vscode/mcp.json	npx hatch3r init
Cline / Roo	.roo/mcp.json	npx hatch3r init

Connecting MCP Servers

Cursor

1. Run npx hatch3r init and select MCP servers when prompted
2. Config is written to .cursor/mcp.json and secrets template to .env.mcp
3. Fill in your API keys in .env.mcp (see Managing Secrets)
4. Restart Cursor for changes to take effect
5. In Cursor: Settings -> Tools & MCP -- verify servers show a green dot

If using the Cursor plugin, the plugin provides mcp.json at the project root. Cursor loads project-level config from .cursor/mcp.json (takes precedence over global ~/.cursor/mcp.json).

Claude Code

Config goes to .mcp.json. Claude Code reads it from the project root. Fill in .env.mcp, source it, and restart Claude Code after init.

Other Hosts

See the Adapter Capability Matrix for per-tool output paths.

Managing Secrets

The .env.mcp file

hatch3r init generates a .env.mcp file at the project root containing every environment variable your selected MCP servers need. This file is covered by .gitignore (the .env.* pattern) and must never be committed.

# .env.mcp (generated by hatch3r init)
GITHUB_PAT=ghp_xxxxxxxxxxxx
BRAVE_API_KEY=xxxxxxxx

When you add new MCP servers and run hatch3r init or hatch3r sync, any new variables are appended to .env.mcp without overwriting existing values.

How secrets are loaded per editor

VS Code / Copilot -- Secrets load automatically. The generated .vscode/mcp.json includes envFile: "${workspaceFolder}/.env.mcp" on every STDIO server, so VS Code reads the file natively.

Cursor -- Source .env.mcp before launching:

set -a && source .env.mcp && set +a && cursor .

Alternatively, add your tokens to ~/.zshrc / ~/.bashrc for persistent access, or paste them in Cursor: Settings -> Tools & MCP -> pencil icon next to each server.

Claude Code -- Source .env.mcp before launching:

set -a && source .env.mcp && set +a && claude

Other editors -- Same sourcing pattern. See the Adapter Capability Matrix for per-tool details.

Required environment variables

Default servers

Server	Env var	How to get it
GitHub	GITHUB_PAT	Create a PAT -- see GitHub PAT scopes
Brave Search	BRAVE_API_KEY	Brave Search API -- free tier: 2,000 queries/month

Opt-in servers (enable during init)

Server	Env var	How to get it
Sentry	SENTRY_AUTH_TOKEN	Sentry Auth Tokens
Postgres	POSTGRES_URL	Your PostgreSQL connection string
Linear	LINEAR_API_KEY	Linear API keys

GitHub PAT scopes

Classic PAT (Settings -> Developer settings -> Personal access tokens -> Tokens (classic)):

• repo -- full control of private repositories (read/write code, issues, PRs, projects)
• read:org -- read org and team membership (needed for org projects)

Fine-grained PAT (recommended): Grant repository permissions for Contents, Issues, Pull requests, Metadata. Add Organization permissions for Members (read) if using org projects.

Verifying connection

1. Restart your editor after setting secrets
2. Check MCP status: Cursor shows green dots in Settings -> Tools & MCP
3. In chat/composer, check "Available Tools" -- you should see tools from each enabled server

Server Details

• GitHub -- Remote server at https://api.githubcopilot.com/mcp/. Uses X-MCP-Toolsets for repos, issues, pull_requests, projects
• Context7 -- No secrets. Fetches up-to-date library docs
• Filesystem -- No secrets. Uses . (project root) as the allowed directory
• Playwright -- No secrets. Browser automation
• Brave Search -- Requires BRAVE_API_KEY