ProjectBrain MCP

ProjectBrain MCP is a Model Context Protocol (MCP) server for project planning and execution workflows. It exposes tools for tasks, decisions, facts, milestones, comments, and team messaging through a Streamable HTTP endpoint.

What it does

• Serves MCP tools over HTTPS at https://mcp.projectbrain.tools
• Allows unauthenticated MCP discovery requests for initialize, notifications/initialized, ping, tools/list, resources/list, resources/templates/list, and prompts/list
• Authenticates bearer tokens (JWT or API key) for all tool execution and data access
• Provides MCP OAuth metadata endpoints
• Executes tool actions against the ProjectBrain API

Service endpoints

• GET /health
• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server
• POST /

Configuration

Set these environment variables:

• SERVER_URL (default: http://localhost:8000)

Base URL of the ProjectBrain API.

• MCP_SERVER_URL (default: same as SERVER_URL)

Public base URL used in OAuth resource metadata.

• JWT_SECRET_KEY

Secret used to validate JWT bearer tokens.

• JWT_ALGORITHM (default: HS256)
• CORS_ORIGINS (default: ["http://localhost:5173"])

Accepts either a JSON array or a comma-separated list.

• MCP_REQUEST_TIMEOUT_SECONDS (default: 30)
• MCP_UNAUTH_DISCOVERY_METHOD_SCAN_BYTES (default: 8192)

Max unauthenticated request bytes scanned to detect JSON-RPC method in lightweight middleware parsing.

• SENTRY_DSN

Sentry DSN for MCP service error/performance reporting.

• SENTRY_TRACES_SAMPLE_RATE (default: 0.2)

Trace sample rate passed to sentry_sdk.init.

• SENTRY_SEND_DEFAULT_PII (default: false)

Set to true to include richer MCP request/response context with MCPIntegration (review data collection implications before enabling).

• SENTRY_ENVIRONMENT (optional)

Sentry environment tag (for example: production, staging).

Local development

From repository root:

1. Install backend dependencies:

• cd api && uv sync --locked

1. Start the MCP server:

• PYTHONPATH=mcp api/.venv/bin/uvicorn api_adapter:app --app-dir mcp --host 0.0.0.0 --port 8001

Directory structure

• api_adapter.py — FastAPI app entrypoint and auth middleware
• server.py — MCP tool definitions and HTTP client adapter
• runtime.py — runtime config and request-scoped auth context