// guides · 02

MCP — external servers and tools

The Model Context Protocol wraps external servers as first-class agent tools. Okami speaks JSON-RPC over stdio (no extra dependency), lists each server's tools and…

Open in full documentation GitHub

Declare a server

Servers live under mcp.servers in okami.yaml. Each has command + args (and optional env/headers). Tools enter the registry as mcp__<server>__<tool>.

okami.yaml

mcp:
  servers:
    filesystem:
      command: npx
      args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
    github:
      command: npx
      args: ['-y', '@modelcontextprotocol/server-github']
      headers: { Authorization: '${GITHUB_TOKEN}' }   # secret via env, never literal

Inspect the tools

okami mcp     # lists servers and the tools they expose

Trust store

MCP is an attack surface: a third-party server's tool may read/write/access network. Okami treats each server by trust level and requires go/no-go per capability.

level	behavior
untrusted	a tool with no manifest requires approval (doesn't trust the pretty name)
reviewed	the policy ceiling by default (`mcp.max_trust: reviewed`)
trusted	bypasses the per-capability gate — sits ABOVE the policy ceiling

Tools & exit criteriaHow every tool is validated.Security & policyThe full trust store.

Open this page in the interactive docs