Scenario: Add an MCP server to an existing project

When to use #

You already have an aidokit-scaffolded project and want to wire in an MCP server from the curated catalog. Optionally scope the MCP to specific workflow roles so it only loads for, say, the Researcher and Architect.

At a glance #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart LR
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;
  you(["you"]):::actor
  list["aidokit mcp list"]:::cli
  add["aidokit mcp add "]:::cli
  scope["--scope "]:::pack
  doctor["aidokit doctor"]:::cli
  ok(["MCP wired and verified"]):::ok
  you --> list --> add --> scope --> doctor --> ok

Step-by-step #

1. List what is already installed #

aidokit mcp list

Expected: a table of MCP ids, their scope, and the roles they are bound to.

2. Add the picked MCPs #

For each MCP from the catalog you want, run:

aidokit mcp add <name>
# optionally scope to roles
aidokit mcp add <name> --scope researcher,architect

Security-sensitive entries (filesystem, graphify) always prompt for explicit confirmation, regardless of --yes.

Expected: one success line per MCP; the engine directory's mcp.json is updated.

3. Verify #

aidokit doctor

Expected: every added MCP loads cleanly under the project's adapter, and any role-scope mismatch is flagged.

Common mistakes #

Adding filesystem or graphify without first reading concepts/security-model.md — these grant broad capabilities.
Forgetting that --scope is additive: re-running aidokit mcp add <name> --scope X replaces the scope, it does not append.
Editing mcp.json by hand — the manifest will drift from what aidokit doctor verifies.