MCP Server

Connect AI assistants to Durabull read-only queue diagnostics through the hosted MCP endpoint.

Durabull exposes a read-only Model Context Protocol (MCP) server on the same origin as the web app and API.

{APP_BASE_URL}/mcp

Example: https://app.durabull.io/mcp

MCP runs inside the unified Durabull API process. There is no separate MCP port or container in phase 1.

What MCP provides

Phase 1 ships diagnostic tools only — no queue mutations, retries, pauses, or purges.

GA status: Read-only MCP is implemented on the unified deployment. Before announcing production use, complete the release checklist (staging smoke, config verification). Full GA doc set: GA index (ADR, compliance, security closure, validation evidence).

Tool	Scope	Purpose
`ping`	`mcp:discover`	Transport smoke check
`list_connections`	`mcp:jobs:read`	Connections visible to the principal
`list_queues`	`mcp:jobs:read`	Queue inventory for a connection
`get_queue`	`mcp:jobs:read`	Queue detail and counts
`list_jobs`	`mcp:jobs:read`	Paginated job summaries
`get_job`	`mcp:jobs:read`	Safe job detail
`get_job_logs`	`mcp:logs:read`	Paginated job logs
`get_job_stacktraces`	`mcp:logs:read`	Attempt-indexed stacktraces
`get_failure_events`	`mcp:failures:read`	Alert/failure events
`get_queue_metrics`	`mcp:diagnostics:read`	Queue metrics window
`get_workers`	`mcp:jobs:read`	Worker snapshots
`explain_job_failure`	`mcp:diagnostics:read` + `mcp:jobs:read` + `mcp:logs:read` + `mcp:failures:read`	Deterministic failure summary

Authentication

Remote MCP clients authenticate with OAuth 2.1 bearer tokens issued by Durabull (Better Auth MCP plugin).

Discover protected resource metadata at GET /.well-known/oauth-protected-resource (or /api/auth/.well-known/oauth-protected-resource).
Register an OAuth client (POST /api/auth/mcp/register). On internet-facing deployments, registration is unauthenticated (rate-limited only) — monitor volume at the edge and prefer pre-provisioned clients where possible.
Send the user through authorization code + PKCE at /api/auth/mcp/authorize with prompt=consent and resource={APP_BASE_URL}/mcp.
The user signs in (if needed) and approves scopes on /consent.
Exchange the authorization code at /api/auth/mcp/token with the same resource value.
Call MCP with Authorization: Bearer <access_token>.

Canonical resource URI:

{APP_BASE_URL}/mcp

APP_BASE_URL must match the public origin clients use to reach /mcp (including port in local dev).

See the MCP OAuth operator guide for HTTP status semantics and discovery endpoints.

Scopes

Scope	Grants
`mcp:discover`	Transport + `ping`
`mcp:jobs:read`	Connection/queue/job/worker reads
`mcp:logs:read`	Logs and stacktraces
`mcp:failures:read`	Failure/alert events
`mcp:diagnostics:read`	Queue metrics; required (with jobs/logs/failures scopes) for `explain_job_failure`

Delegated users receive scopes from OAuth consent. Service accounts require explicit policy bindings per tool/scope.

Safety controls

Authenticated callers still receive:

Output redaction — sensitive keys and inline secrets stripped; _mcpSafety.redactionCount when redactions occur
Rate limits (when NODE_ENV=production) — 120 HTTP requests/min on /mcp ingress (initialize, session, and tool RPCs); 60 calls/min per tool per bearer (30/min for get_job_logs, get_job_stacktraces, get_failure_events, get_queue_metrics, explain_job_failure)
Audit — best-effort mcp_audit_event rows for tool calls (may drop under backpressure; see runbook)

Operators: telemetry signals, SQL examples, and incident playbooks are in the MCP operations runbook.

Local development

Authless mode (DURABULL_AUTHLESS=true) is for local/private setups only. Never enable authless mode on Durabull Cloud. If authless is reachable from a network, set a strong MCP_AUTHLESS_BEARER_TOKEN — the non-production default token is for localhost dev only.

For monorepo dev with the Vite app, set APP_BASE_URL to the web origin (http://localhost:5173) so /mcp and OAuth discovery share one origin (the dev server proxies to the API). For API-only smoke scripts, use the API port (http://localhost:3001 or http://localhost:3000 in Docker).

For test commands and CI evidence, see validation evidence. Run mcp:e2e only against local or staging databases (see runbook).

Deployment and operations

MCP is always on when the Durabull API runs. Platform-specific deploy notes:

Post-deploy smoke and operations: MCP operations runbook.