Adding or changing MCP

The MCP server at /api/mcp/ is the project-scoped agent API. It shares domain services with the Console and REST API; it does not proxy either. This skill is for changing the server. The skills that overmind init installs for users live in overmind/skills/; never copy this file there.

MCP-impact classification

Every new or changed capability, API workflow or Console workflow needs an explicit MCP decision in the same change. Classify it:

• MCP-ready — an agent can discover, inspect or progress the workflow. Add or update the smallest tool, resource or prompt.
• CLI-guided — the workflow needs local files, repository edits, binary transfer or third-party credentials. MCP returns state, exact IDs and a structured action; the CLI or SDK does the local work.
• Frontend-only — presentation, navigation, visual exploration or billing with no useful agent action. The underlying state stays readable through MCP when agents need it.
• Out of scope — destructive operations stay off the public surface until designed and authorized.

Record the reason when a change is not MCP-ready. The Console must not become the only way to finish an agent-relevant workflow. Textual state is the baseline; charts may stay visual.

Shape of the server

MCP client
  -> /api/mcp/ Streamable HTTP
  -> MCPAuthMiddleware + MCPTransportMiddleware
  -> request-scoped MCPContext
  -> low-level MCP Server callbacks
  -> curated ToolCatalog
  -> feature tool adapter + strict input/output contracts
  -> existing domain service / model / task
  -> CallToolResult + resource links
  -> client reads overmind:// resources or polls a job receipt

overbae/api/mcp.py is the entrypoint. overbae/asgi.py makes the MCP Starlette app the outer ASGI app and mounts Django inside it at /; its middlewares pass non-MCP paths through. /api/mcp/ and the OAuth routes never reach Django's ASGIHandler, so the outermost RequestThreadMiddleware gives each request a ThreadSensitiveContext (without it every thread-sensitive sync_to_async call shares one thread) and closes the request's DB connections. services/mcp/server.py owns the SDK server, stateless transport, protocol checks and middleware order. Never create a second MCP app or a feature-specific server.

With a PostHog token, the server sends $mcp_* analytics. Events carry identity, project_id and, on failure, error_code: before_send drops arguments, results and error text, $exception capture is off, and input models forbid extra fields so argument injection stays off. tests/test_mcp_analytics.py holds these rules.

Product activity is separate from analytics. Shared activity records back the Console bell and onboarding milestones; overmind://activity pages those same outcomes with offset, limit and path=agent|data. Account credentials add project_id. report_onboarding_progress records the coding agent’s verified completed count for one UUID run_id against the current SDK’s ten stages. These progress receipts stay out of the notification feed; the landing page renders their roadmap. The Console subscribes to /api/activity/events/ for project-scoped snapshots and invalidates asset queries without page reloads. Task status changes update the original activity ID; transformation publication reuses that task record. Only newly observed changes trigger the brief asset highlight. Reconnects reconcile the durable snapshot; onboarding receipts also advance the stream revision. Reads and status polls never create action notifications or mark them seen. Successful initialization retains credential-bound client identity; connection milestones deduplicate by user, project scope and reported client family, including across credential refreshes. Unknown or ambiguous identity stays generic; client-reported logos never establish continuous agent presence.

Layer ownership

Tools call the domain layer directly. They may share serializers or entity-resolution helpers, but never call frontend code, Console registries or an internal REST endpoint. If a Console workflow has no reusable service, fix the service boundary first.

Authentication

• Every request authenticates before the SDK callback. Account API keys and OAuth grants reach the user's active projects; project keys stay on one project. Every API key enforces its allowed IPs, and all credentials enforce read and write.
• Account credentials pass project_id per operation; list_projects returns accessible projects. The catalog checks membership before the handler runs, and handlers get the project only from MCPContext. Selection is per request, never session state.
• OAuth uses the SDK protocol handlers with hashed codes and tokens in models/mcp_oauth.py. Public clients register with auth method none and S256 PKCE, against the exact MCP_SERVER_URL resource. Access tokens last one hour; refresh tokens rotate, and reuse revokes the family. OAuth works only on MCP; API keys use X-Api-Key or Authorization: Bearer (or Api-Key).
• ToolDefinition.required_scopes records the capability a tool needs; visibility enforces read versus write. Granular enforcement, if added, belongs in the catalog or auth layer for every tool, never in a handler.
• Tool names containing delete, remove, cancel, retry or undeploy are rejected unless they are in _ALLOWED_LIFECYCLE_TOOLS (catalog.py); the destructive ones are also in _DESTRUCTIVE_TOOLS. Adding to either list needs explicit approval. Do not infer generic destructive operations from the existing entries.

Adding or changing a tool

1. Classify the change. Reuse a tool when the agent intent is unchanged; do not mirror a REST endpoint because it exists.
2. Add strict request and response models in services/mcp/contracts/<domain>.py. Extend MCPModel, bound collections and strings, reject unknown fields.
3. Put the handler in services/mcp/tools_<domain>.py. Resolve entities inside context.project, call the domain service, and raise MCPError for expected failures.
4. Register one ToolDefinition in that module's register_<domain>_tools with accurate read_only, idempotent, open_world, required_scopes, cost_class and async_mode. Import a new domain module into CATALOG only when it is genuinely new.
5. Return the declared output model, never a raw dict. Add resource or resource_links for durable entities.
6. For background work, return a JobReceipt with kind, id, status and an overmind://jobs/{kind}/{id} resource, and teach get_job and the resource reader that kind.
7. Operations that start paid or long work take a stable request_key; an identical retry returns the original receipt and a changed payload conflicts.
8. Bump CONTRACT_VERSION in services/mcp/__init__.py with every contract change. overmind://interface/current publishes it with the catalog fingerprint.
9. Keep tools/list within MAX_MANIFEST_BYTES (tests/mcp_fixtures.py); output schemas and secrets stay out of discovery.

Keep handlers thin. Never copy a Console view's business logic into tools_*.py.

Results and errors

ToolCatalog.call validates input, runs the handler, validates output, then tool_result emits the same object as structuredContent and as compact JSON text for clients that read only text. Matching resource/resource_links also become native ResourceLink content. Identifiers, costs, rows and receipts are contract fields, never prose only.

MCPError becomes {"error": {"code", "message", "retryable", "fields"}} with isError=true. Unexpected failures become a safe internal_error. Messages come from authored text or authored domain errors; never leak raw exceptions, provider responses, tokens or tracebacks.

Bound tool responses losslessly: page large results, or fail with a typed error such as query_result_too_large, rather than clip values. Action receipts stay compact and point to a resource with the full evidence.

Resources, jobs and local files

• Resources are durable, read-only state, not a second mutation API. Implement the project-filtered payload in resources.py, register its template, and build links with resource_link.
• safe_json is the resource serialization boundary. It drops keys that name a token, secret, password, cookie, credential, authorization, API key or private key (numeric token counts stay), and it truncates strings at 12,000 characters and collections at 100 entries. safe_finetune_progress also removes presigned and checkpoint URLs.
• Reads never invoke a worker or a provider. Operational, monitoring and evaluation evidence come from receipts that background controllers saved.
• MCP carries JSON, not local bytes. Uploads, exports, checkpoints, repository edits and local execution return a CLI guidance resource with exact IDs and argv; MCP resumes at the resulting resource.
• Essential client-independent guidance belongs in server instructions, tool descriptions and resources. Plugins and installed skills are optional; never make one a prerequisite or the enforcement boundary. The overmind/.{claude,codex,cursor}-plugin/ versions match SKILLS_VERSION in overmind/overmind/skills_db.py.

Prompts and catalog discipline

Prompts are named, parameterized recipes. They name the public tools to call, mark approval and human-action points, and end with a decision checkpoint. Do not add a prompt to cover a missing tool, or a tool for one prompt sentence.

Organize the catalog by intent: discovery and read, mutation, background work, CLI handoff. A description states the goal, the main constraint and the next state. Prefer one broad inspection tool to near-duplicate filters; distinct state transitions deserve distinct tools.

Tests

Follow the testing policy in AGENTS.md and the run-tests skill. A tool's happy path belongs to its vertical's journey; these files hold the edge cases. Call tools through mcp_fixtures.call_tool; only auth and transport tests go through the ASGI app (mcp_fixtures.asgi_db).

Completeness

• The MCP classification, and the reason when not MCP-ready, is in the PR.
• The tool, resource or prompt uses the shared domain service and project-scoped authorization.
• Inputs, structured outputs, resource links and async receipts are defined and tested.
• The entity has a read path after creation, including polling for background work.
• Local-file workflows use CLI guidance, not an MCP byte-transfer workaround.
• CONTRACT_VERSION, the catalog, prompts, resources, the user-facing skills in overmind/skills/ and the MCP tests change together. Regenerate the API client when the REST contract changed.

Activity sequence_key identifies a project-scoped dataset preparation workflow: creation, upload, import, saved transformations, previews and publication. Pipeline runs resolve their dataset from the retained run record. Other edits and consumers remain separate. The Console connects adjacent matching events without declaring whole-task completion.

An explicit start_dataset_preparation / update_dataset_preparation lifecycle keeps the dataset Preparing between jobs until the agent finishes. Inspect it through inspect_dataset_workbench.preparation_workflow. Child source and pipeline activity remains recorded but is folded into its single evolving notification; child updates touch the parent timestamp to invalidate Console assets. Pause is explicitly reported, not inferred from a client disconnect.