Using MCP

This guide walks you through setting up MCP servers from zero to production.

Step 1: Install MCP support

cd ~/.monoclaw/monoclaw-runtime
uv pip install -e ".[mcp]"

Step 2: Find a server

Browse available servers at github.com/modelcontextprotocol/servers.

For this guide, we'll use the GitHub MCP server.

Step 3: Configure the server

Add to ~/.monoclaw/config.yaml:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Generate a GitHub token at github.com/settings/tokens with repo scope.

Step 4: Verify

monoclaw doctor

Look for the MCP section. You should see:

✅ MCP: github (6 tools loaded)

Step 5: Use in chat

List my recent GitHub issues

Mona will use the GitHub MCP tools to fetch and display your issues.

Step 6: Filter tools

The GitHub server has many tools. Limit to what you need:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
    tool_filter:
      include:
        - "search_repositories"
        - "get_file_contents"
        - "list_issues"

Step 7: Add multiple servers

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

  sqlite:
    command: uvx
    args: ["mcp-server-sqlite", "--db-path", "~/.monoclaw/data.db"]

  fetch:
    command: uvx
    args: ["mcp-server-fetch"]

Step 8: Test with a workflow

Search GitHub for "monoclaw-runtime", read the README, and summarize what the project does.

Mona will:

1. Use search_repositories to find the repo
2. Use get_file_contents to read README.md
3. Summarize for you

Production checklist

• Use tool_filter to limit exposed capabilities
• Set utility_tool_policy: hide to reduce noise
• Review MCP server code before installing
• Use separate tokens per server (don't reuse GitHub tokens)
• Monitor ~/.monoclaw/logs/mcp/ for errors
• Test with --dry-run before production

Troubleshooting