aidokitwiki
User Docs Wiki

Scenario: Custom MCP servers / custom stack

Audience-User Status-Shipped v0.5 Spec-MCP Catalog

When to use #

You have non-default MCP servers (internal tooling, niche providers), or your stack isn't one of the five first-party packs (node-ts, node-js, python, react, go). You need to bring your own and have aidokit wire them into the manifest.

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;
  cat["aidokit mcp catalog"]:::core
  add["aidokit mcp add"]:::cli
  cfg["adapter MCP config"]:::artifact
  user["user's AI CLI"]:::external
  cat --> add --> cfg --> user
  custom["custom stack pack"]:::pack
  init["aidokit init"]:::cli
  skills["emitted skills"]:::artifact
  custom --> init --> skills

Step-by-step #

1. List installed MCPs #

aidokit mcp list

Expected: the catalog MCPs already wired into the project's manifest, with per-role scoping.

2. Add a catalog MCP #

aidokit mcp add <name>

See the canonical 8-entry catalog at reference/mcp-catalog-reference.md.

Expected: the MCP is appended to the manifest and emitted into the adapter's MCP config.

3. Add a non-catalog MCP #

aidokit mcp add --url <url> --name <name>

Verify availability with aidokit manifest first — non-catalog adds are a v0.5+ surface; if your version errors here, you're pre-0.5.

Expected: a custom entry appears in the manifest with source: "custom".

4. Bring a custom stack pack #

For the full SDK and template, see tutorials/author-a-stack-pack.md. Quick start:

aidokit new stack-pack <slug>

Expected: a scaffolded package under packages/stack-pack-<slug>/ ready to be filled in.

5. Verify #

aidokit doctor

Expected: the new MCP + stack pack show up in the manifest with green status.

Common mistakes #

See also #