Add an MCP Catalog Entry

Purpose #

Add one entry to the MCP catalog with a one-file edit. Worked example: ADR-0015 (graphify).

Big Picture #

The catalog is data — a TypeScript const array in @aidokit/mcp-catalog. Adding an entry is a single PR. The checklist at .docs/docs/specs/mcp-catalog.md Appendix B is the gate.

How It Works #

1. Verify the MCP works #

Install and run the MCP locally against a real project. Confirm:

The install command works exactly as you'll list it in the catalog.
It works under the target CLI (Claude Code at minimum; ideally also Codex).
Its capability scope matches what its docs claim.

2. Decide the security profile #

securitySensitive: true is required when any of (.docs/docs/specs/mcp-catalog.md §10.1):

It can write or delete files outside the engine directory.
It can execute arbitrary shell commands.
It can make outbound network calls to user-controlled URLs.
It accesses credentials, tokens, or secrets.
It accesses cloud resources with write privileges.
It can persist data beyond the current project's scope.

Be honest. Marking false when it should be true is a security violation, not a marketing decision.

3. Decide the triggers #

OR-only grammar from mcp-catalog reference. Don't use always unless universally useful. Sensitive entries should always use triggers: ['never'].

4. Decide the default scope #

suggestedFor is the minimum set of roles for which the MCP is appropriate. Never "all roles." Sensitive entries usually have suggestedFor: [] (manual scoping at add time).

5. Write the entry #

packages/mcp-catalog/src/catalog.ts:

{
  id: 'my-mcp',                                       // kebab-case, permanent
  name: 'My MCP',
  purpose: 'One-line description — under 100 chars.',
  suggestedFor: ['researcher'],
  triggers: ['stack.hasFrontend'],
  securitySensitive: false,
  install: {
    'claude-code': {
      command: 'claude mcp add my-mcp -- npx -y @example/my-mcp',
      requiresNetwork: true,
      minCliVersion: '2.1.32',
    },
    'codex': {
      configBlock: {
        target: '~/.codex/config.toml',
        content: '[mcp_servers.my-mcp]\ncommand = "npx"\nargs = ["-y", "@example/my-mcp"]',
        mode: 'merge',
      },
      requiresNetwork: true,
    },
  },
  homepage: 'https://github.com/example/my-mcp',
  tags: ['research', 'frontend'],
  // optional: prereqs: ['python>=3.10']   for non-Node MCPs (see ADR-0015)
}

If the MCP needs per-MCP prereqs (e.g. a Python interpreter for graphify), use the optional prereqs: string[] field per ADR-0015. The CLI prints the hint when the user opts in; aidokit does not install them (ADR-0008).

6. Add a test #

The catalog parity test (already in packages/mcp-catalog/test/) iterates every entry and validates it against MCPDefSchema. Your entry must pass without modification. If you used a new field (e.g. prereqs), update the schema first.

If your entry uses a new trigger form, add a trigger-evaluation test case in packages/mcp-catalog/test/triggers.test.ts.

7. Document in the spec #

Add the entry under .docs/docs/specs/mcp-catalog.md §11 with the same fields. Also add it to reference/mcp-catalog-reference.md.

8. If the entry is security-sensitive, also write an ADR #

Worked example: ADR-0015. The ADR captures the trust boundary, the prereq story, and why this entry is necessary now.

9. Changeset #

pnpm changeset
# minor bump for @aidokit/mcp-catalog

Example: walking through ADR-0015 (graphify) #

The graphify entry illustrates the full pattern:

securitySensitive: true because graphify reads the project tree and sends content to an external model.
trigger: 'never' because sending repo contents off-host should never auto-suggest.
prereqs: ['python>=3.10', 'uv or pipx'] because graphify is a Python tool, but Python is not promoted to a CLI-wide prereq (the prereq scope of aidokit stays Node-only per ADR-0008).
Install via uvx graphifyy mcp so aidokit doesn't run pip install on the user's behalf.
ADR captures the trust boundary so reviewers can confirm the security model is intact.

Common Mistakes #

Removing an entry. Entries are append-only. Deprecate with deprecated: true and (if applicable) replacedBy: '<new-id>' (ADR-0007 §7).
Renaming an id. Ids are permanent. New names ship as new entries.
Combining triggers with AND. Not supported. Split into two entries.
Setting securitySensitive: false for an entry that meets sensitive criteria.
Skipping the homepage/tags fields. Required for marketplace browsing (post-v1.0) and discoverability today.
Adding the entry to a stack pack instead of the catalog. Stack packs reference catalog ids only.

Checklist (from spec Appendix B) #

[ ] Ran the MCP locally; it works.
[ ] suggestedFor is the minimal correct set.
[ ] Triggers honest (not always unless universally useful).
[ ] securitySensitive reflects real capability.
[ ] Install specs for at least one adapter.
[ ] homepage + tags populated.
[ ] Catalog parity test passes.
[ ] Documented in .docs/docs/specs/mcp-catalog.md §11.
[ ] Mirrored in reference/mcp-catalog-reference.md.
[ ] ADR drafted if security-sensitive or model-altering.
[ ] Changeset filed (minor bump).