MCP

Connect your favorite MCP client (Claude Code, Claude Desktop, Cursor, Windsurf) to the Infracodebase MCP server. The MCP server brings the Infracodebase governance layer to your local agent experience.

Quick start

1. Get a Personal Access Token. See Access Tokens for how to create one.

2. Connect the MCP server to your favorite MCP client - supports any mcp client (Claude Code, Cursor, etc.) via stdio.

bash

claude mcp add infracodebase --scope user \
  --env INFRACODEBASE_TOKEN=icb_pat_xxx \
  -- npx -y @infracodebase/mcp@latest

--scope user registers infracodebase for every project. Without it, the server shows as disconnected when you cd into a different repo. Run /mcp in any session to confirm.

3. That's it. Your agent now has Infracodebase's governance layer. It generates compliant IaC, cites the rules it follows, and catches issues before you commit.

Tools available

A read-only token can call any tool in the first group. A read and write token can also call the second group. Personal tokens pick a coarse read vs. execute scope; enterprise tokens stamp the underlying permissions directly. See Access Tokens for the full permission model.

Read-only

Tool	Purpose
`get_workspace_context`	Front door. Resolves repo → workspace, returns coding guidelines, ruleset metadata, and latest compliance state.
`get_ruleset_details`	Full rule contents for one ruleset.
`get_compliance_evaluation`	A specific compliance evaluation (latest by default, or by id / commit SHA).
`list_compliance_findings`	Per-rule findings (optionally filtered by status).
`get_compliance_eval_spec`	The CI evaluator's framing, so local advisory reasoning can mirror it.
`list_modules`	The workspace's approved module catalog, so the agent reaches for sanctioned modules.
`list_enterprises`	Your enterprises with role and workspace count.
`list_workspaces`	Workspaces you can access (optionally filtered to one enterprise).
`list_enterprise_resources`	Rulesets, MCP servers, and workflows available to attach to a workspace.
`list_github_installations`	GitHub orgs your enterprise is connected to.
`list_github_repos`	Repos visible through a GitHub connection.

Read and write

Tool	Purpose
`create_workspace`	Create a workspace, attach resources, optionally link it to a GitHub repo in one call.
`link_workspace_to_repo`	Connect an existing workspace to a GitHub repo.
`update_workspace_resources`	Add or remove rulesets, MCP servers, and workflows on a workspace.

infracodebase never sees your local files.

Managing tokens

The token lives in your MCP client's env, not on disk. To rotate it, update INFRACODEBASE_TOKEN in the client config (or re-run claude mcp add with the new value) and restart the client. To revoke or audit tokens, see Access Tokens. Revocation is immediate.

Self-hosting

The MCP server is open source. If you can't reach public npm, or want to run a pinned build, clone and run it directly - point your client at the built entrypoint with the same env:

bash

git clone https://github.com/onwardplatforms/infracodebase-mcp.git
cd infracodebase-mcp
npm install
npm run build

json

{
  "mcpServers": {
    "infracodebase": {
      "command": "node",
      "args": ["/abs/path/to/infracodebase-mcp/dist/index.js"],
      "env": { "INFRACODEBASE_TOKEN": "icb_pat_xxx" }
    }
  }
}

To target a self-hosted infracodebase API instead of the SaaS, add INFRACODEBASE_API_URL to the same env block (or pass --api-url); unset, it defaults to https://infracodebase.com/api/v1.

json

"env": {
  "INFRACODEBASE_TOKEN": "icb_pat_xxx",
  "INFRACODEBASE_API_URL": "https://infra.your-company.com/api/v1"
}

See CONTRIBUTING.md in the repo for development setup.

Troubleshooting

MCP shows as disconnected when you cd to a different repo: registered at project (local) scope. Re-add with --scope user (Claude Code) or use the global config path (Cursor / Windsurf / Claude Desktop).
MCP server fails to start or the token is rejected: the server runs a startup health check and logs to stderr - check your client's MCP logs. A token rejected (HTTP 401/403) line means INFRACODEBASE_TOKEN is missing, invalid, or expired; update it in the client's env and restart. A could not reach <url> line means the endpoint is wrong - check INFRACODEBASE_API_URL.
get_workspace_context returns status: "unlinked": the repo isn't configured as a workspace in infracodebase. Ask the agent to create one, or set it up in the web app.
get_workspace_context returns status: "no_access": a workspace exists but your token's user (or the enterprise token's workspace scope) can't see it. Ask an admin for access.
401, 403, or 429 errors: token-side issues. See Troubleshooting in Access Tokens. Replace INFRACODEBASE_TOKEN in your client config with a fresh token and restart.