MCP

ForgeaX CLI connects to external tools and data sources via the Model Context Protocol (MCP).

Config files

Auto-discovered and merged (project overrides user):

1. ~/.forgeax/mcp.json
2. <cwd>/.forgeax/mcp.json

Or pass a file explicitly:

forgeax --mcp /path/to/mcp.json

Shape

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"]
    }
  }
}

Exact server fields follow the implementation; unknown keys are passed through to the MCP client assembly layer.

Token injection

Avoid committing secrets into JSON:

forgeax --mcp-token github=GITHUB_TOKEN
forgeax --mcp-token =GLOBAL_TOKEN_ENV     # wildcard: same env name for all servers

Syntax: server=ENV_NAME or =ENV_NAME (wildcard).

As an MCP server (reverse)

Expose this kernel’s tools to other MCP clients:

forgeax mcp-serve
forgeax mcp-serve --allow-writes

• Default is read-leaning; mutating tools need --allow-writes or FORGEAX_MCP_ALLOW_WRITES=1
• Non-interactive: ask permissions are always denied; deny still forced
• Distinct from --serve (AgentKernel sidecar): one exposes tools, the other exposes kernel RPC

Troubleshooting

Symptom	Check
Tools missing	Confirm mcp.json exists and JSON is valid; inspect startup logs
Auth failures	Ensure --mcp-token / server env point at real env vars
Timeout / spawn failure	Can you run command + args directly on this machine?

More in Troubleshooting.