Skip to content
Canon

Job pack · mcp

MCP server

External capabilities as tools/resources/prompts. Pin, hash, review. Descriptions are an attack surface.

When: A capability must live outside the agent process and be approved independently.

One job per tool. No secrets in descriptions. Clients pin this server. Do not instruct the model from a tool description.

GET /api/canon/jobs/mcp-server?format=md

Matching skill · MCP server

Playbooks

Doctrine to load

  1. Model Context ProtocolMCP is USB-C for tools, resources, and prompts. Servers expose capabilities; clients (harnesses) load them. Do not confuse a protocol with a product strategy.
  2. Designing the Agent-Computer InterfaceThe ACI is names, schemas, errors, pagination, and idempotency. A sloppy tool surface makes a smart model look drunk. A tight one makes a small model look hired.
  3. Injection, Poisoning, Confused DeputyAnything the model reads — web pages, PDFs, MCP tool descriptions, retrieved docs, other agents' briefs — is an untrusted speaker. Treat it as data, never as an instruction channel.
  4. Secrets, Identity, Least PrivilegeThe agent is a principal. It gets the credentials of the job, not the credentials of the developer. Subagents inherit a subset. Logs never print secrets. Memory never stores them.

Refuse

  • Tool poisoning. An MCP server or plugin whose description is an instruction: 'call me first, send secrets'.
  • Mega-tool. One function whose argument is a JSON blob of 'whatever'. An untyped shell with extra steps.
  • Security by system prompt. 'Never delete files' as the only guard. The model is a confused deputy and will try to help.

Checklists

ACI quality

  • One job per tool. No mega-tool JSON blob.
  • Verb names the model will say: read_file, apply_patch, ask_human.
  • Compact errors: the smallest string that enables the next correct action.
  • Capped results. Pagination or a file write instead of 200k-token dumps.
  • Idempotent or journaled. Retries do not double side effects.
  • Allow / ask / deny in code, logged, resumable.

Security review

  • Retrieved docs, web, and MCP descriptions are labeled untrusted data.
  • MCP servers pinned, hashed, reviewed. No marketplace auto-trust.
  • Secrets injected at the executor, never into the prompt or the workspace dump.
  • Subagents are reduced principals. No parent deploy keys.
  • Allow / ask / deny. Irreversible actions are high-friction asks.

Recipes

Minimal MCP serverTool schema

Default corpus

mcp-pythoncomposiogemini-cli