goclaw-mcp

MCP (Model Context Protocol) server for GoClaw Gateway server management. Enables AI assistants like Claude, Cursor, and other MCP clients to manage your GoClaw AI gateway infrastructure.

Features

• 66 MCP tools covering all GoClaw management operations
• 4 MCP resources for real-time gateway context
• 4 MCP prompts for guided workflows
• Dual transport: stdio (local) + Streamable HTTP (production)
• Enterprise security: audit logging, rate limiting, secret scrubbing, origin validation
• Type-safe: Full TypeScript with Zod schema validation

Quick Start

stdio (Claude Code, Cursor, etc.)

npx goclaw-mcp

Add to your MCP client config:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "goclaw": {
      "command": "npx",
      "args": ["goclaw-mcp"],
      "env": {
        "GOCLAW_SERVER": "http://localhost:8080",
        "GOCLAW_TOKEN": "your-admin-token"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "goclaw": {
      "command": "npx",
      "args": ["goclaw-mcp"],
      "env": {
        "GOCLAW_SERVER": "http://localhost:8080",
        "GOCLAW_TOKEN": "your-admin-token"
      }
    }
  }
}

Streamable HTTP (production, multi-client)

GOCLAW_SERVER=http://localhost:8080 \
GOCLAW_TOKEN=your-token \
GOCLAW_MCP_PORT=3100 \
npx goclaw-mcp-http

MCP endpoint: http://localhost:3100/mcp

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GOCLAW_SERVER | Yes | — | GoClaw gateway URL | | GOCLAW_TOKEN | No | — | Bearer token (determines RBAC role) | | GOCLAW_USER_ID | No | — | Default user ID for multi-tenant scoping | | GOCLAW_MCP_PORT | No | 3100 | HTTP transport port | | GOCLAW_MCP_ALLOWED_ORIGINS | No | localhost | Comma-separated allowed origins | | GOCLAW_MCP_RATE_LIMIT_RPM | No | 60 | Rate limit per session (req/min) | | GOCLAW_LOG_LEVEL | No | info | Log level: debug, info, warn, error |

Available Tools

System (3)

| Tool | Description | |------|-------------| | goclaw_health | Check gateway health | | goclaw_status | Get gateway status | | goclaw_models_list | List available LLM models |

Agents (13)

| Tool | Description | |------|-------------| | goclaw_agent_list | List all agents | | goclaw_agent_get | Get agent details | | goclaw_agent_create | Create agent | | goclaw_agent_update | Update agent | | goclaw_agent_delete | Delete agent | | goclaw_agent_files_list | List context files | | goclaw_agent_files_get | Read context file | | goclaw_agent_files_set | Write context file | | goclaw_agent_files_delete | Delete context file | | goclaw_agent_links_list | List delegation links | | goclaw_agent_links_set | Set delegation link | | goclaw_agent_links_remove | Remove delegation link | | goclaw_agent_share | Share agent with user |

Sessions (5)

| Tool | Description | |------|-------------| | goclaw_session_list | List chat sessions | | goclaw_session_preview | Preview session messages | | goclaw_session_delete | Delete session | | goclaw_session_reset | Reset session history | | goclaw_session_label | Label a session |

Configuration (3)

| Tool | Description | |------|-------------| | goclaw_config_get | Get gateway config | | goclaw_config_apply | Apply full config | | goclaw_config_patch | Patch config fields |

Providers (5)

| Tool | Description | |------|-------------| | goclaw_provider_list | List LLM providers | | goclaw_provider_get | Get provider details | | goclaw_provider_create | Add provider | | goclaw_provider_update | Update provider | | goclaw_provider_delete | Remove provider |

MCP Servers (7)

| Tool | Description | |------|-------------| | goclaw_mcp_server_list | List registered MCP servers | | goclaw_mcp_server_get | Get MCP server details | | goclaw_mcp_server_create | Register MCP server | | goclaw_mcp_server_update | Update MCP server | | goclaw_mcp_server_delete | Remove MCP server | | goclaw_mcp_server_grant_agent | Grant agent access | | goclaw_mcp_server_grant_user | Grant user access |

Skills (5)

| Tool | Description | |------|-------------| | goclaw_skill_list | List skills | | goclaw_skill_get | Get skill details | | goclaw_skill_update | Update skill | | goclaw_skill_grant_agent | Grant agent access | | goclaw_skill_grant_user | Grant user access |

Custom Tools (6)

| Tool | Description | |------|-------------| | goclaw_custom_tool_list | List custom tools | | goclaw_custom_tool_get | Get tool details | | goclaw_custom_tool_create | Create custom tool | | goclaw_custom_tool_update | Update custom tool | | goclaw_custom_tool_delete | Delete custom tool | | goclaw_custom_tool_invoke | Invoke tool directly |

Cron Jobs (6)

| Tool | Description | |------|-------------| | goclaw_cron_list | List cron jobs | | goclaw_cron_create | Create cron job | | goclaw_cron_update | Update cron job | | goclaw_cron_delete | Delete cron job | | goclaw_cron_toggle | Enable/disable cron | | goclaw_cron_run | Trigger cron immediately |

Teams (5)

| Tool | Description | |------|-------------| | goclaw_team_list | List teams | | goclaw_team_get | Get team details | | goclaw_team_create | Create team | | goclaw_team_update | Update team | | goclaw_team_delete | Delete team |

Traces (2)

| Tool | Description | |------|-------------| | goclaw_trace_list | List LLM execution traces | | goclaw_trace_get | Get trace with spans |

Channels (2)

| Tool | Description | |------|-------------| | goclaw_channel_list | List messaging channels | | goclaw_channel_toggle | Enable/disable channel |

Memory (4)

| Tool | Description | |------|-------------| | goclaw_memory_list | List memory documents | | goclaw_memory_get | Read memory document | | goclaw_memory_create | Store memory document | | goclaw_memory_delete | Delete memory document |

Resources

| URI | Description | |-----|-------------| | goclaw://status | Gateway status summary | | goclaw://models | Available LLM models | | goclaw://agents | All agents summary | | goclaw://config | Current gateway config |

Prompts

| Prompt | Description | |--------|-------------| | goclaw_setup_agent | Guide through creating a new agent | | goclaw_troubleshoot | Systematic troubleshooting | | goclaw_review_config | Review config for improvements | | goclaw_optimize_agent | Optimize agent settings |

Security

Built for enterprise environments:

• Secret scrubbing — Tokens, API keys, passwords never appear in logs
• Audit logging — Every tool invocation logged with structured JSON
• Rate limiting — Token bucket per session (HTTP transport)
• Origin validation — DNS rebinding prevention
• Input validation — Zod schemas on all tool parameters
• Auth passthrough — Bearer token forwarded to GoClaw RBAC

Development

# Install
pnpm install

# Build
pnpm build

# Test
pnpm test

# Type check
pnpm lint

# Dev mode (watch)
pnpm dev

License

MIT