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