MCP

Connect Infracodebase to your coding agent: Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Devin, Codex CLI, or any other MCP client.

Prerequisites

Node.js 20.12 or later
An Infracodebase account

Setup

Automatic

bash

npx -y @infracodebase/mcp@latest init --api-url https://infracodebase.com/api/v1

Signs you in through your browser and adds Infracodebase to the MCP clients on your machine. Safe to run again.

Manual

1. Authenticate, in one of two ways:

bash

npx -y @infracodebase/mcp@latest login --api-url https://infracodebase.com/api/v1

Opens your browser and saves a renewable session on this machine. Your client config stays free of secrets.

2. Add the server to your client.

bash

claude mcp add infracodebase --scope user -- npx -y @infracodebase/mcp@latest --api-url https://infracodebase.com/api/v1

On Windows, MCP clients can't start npx directly. Use "command": "cmd" and put "/c", "npx" at the start of args (for Claude Code: -- cmd /c npx -y …). init does this for you.

Drafting before workspace setup

For a repository with no workspace yet, get_workspace_context returns unlinked. The agent can then call plan_workspace_setup to propose an enterprise, connection, and rulesets, and setup_workspace to create or link the workspace once you confirm. If you are building your own setup flow outside MCP, use the REST API's build-context and build-rules endpoints. They return enterprise guidance and selected rules without requiring a workspace first.

Tools available

Your live Infracodebase role determines which enterprises, workspaces, repositories, and actions are available. If you connect a GitHub account, you can also view workspaces whose repository that account can read.

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_vcs_connections`	Version-control connections (GitHub, GitLab) configured for an enterprise.
`list_vcs_repos`	Repos visible through a connection that your personal account can also read.
`plan_workspace_setup`	Proposes how to bring an unlinked repo under governance: enterprise, connection, and rulesets. Makes no changes.

Read and write

Tool	Purpose
`create_workspace`	Create a workspace, attach resources, and optionally link a repository in one call.
`link_workspace_to_repo`	Connect an existing workspace to a repository.
`update_workspace_resources`	Add or remove rulesets, MCP servers, and workflows on a workspace.
`setup_workspace`	Apply a confirmed `plan_workspace_setup` plan: create or link the workspace.

Compliance exceptions

When fixes run out and some rules still fail, the agent can request exceptions for them: a risk acceptance for a real violation someone accepts, or not applicable for a rule that doesn't apply at this level. Everyone requests by default, and a compliance approver reviews. Approvers can grant directly, but the agent only does that when you explicitly say "grant", and it confirms which rules will stop being enforced first. Exception decisions are recorded under your name, so they work with browser login or a personal access token, but not with an enterprise access token.

Tool	Purpose
`list_compliance_exceptions`	Active exceptions and requests waiting on an approver.
`submit_compliance_exceptions`	Request exceptions for a batch of failing rules, or grant them when an approver says so.
`approve_compliance_exception`	Approve a waiting request. Approvers only; takes effect immediately.
`reject_compliance_exception`	Reject a waiting request with a reason. Approvers only.
`revoke_compliance_exception`	End an exception so the rule is enforced again. Approvers only.

infracodebase never sees your local files.

Browser login saves a renewable session in ~/.config/infracodebase/credentials.json with permissions restricted to your user account. Active sessions remain signed in; login is required again after 90 days without a successful refresh or when access is revoked. Temporary network or service failures are retried and do not remove the saved login. With browser login, your MCP client configuration contains no secret. Run npx -y @infracodebase/mcp@latest logout to revoke and remove the saved session, or run login again to reconnect.

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:

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"]
    }
  }
}

For a dedicated or self-hosted instance, pass its API URL to init. It signs you in to that instance and writes the same URL into every client it sets up:

bash

npx -y @infracodebase/mcp@latest init --api-url https://infra.your-company.com/api/v1

This opens the selected deployment's own login flow, so enterprise SSO and directory policies remain in effect.

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 says no saved login was found or the session expired: run npx -y @infracodebase/mcp@latest login --api-url https://infracodebase.com/api/v1. Add --no-open if the browser does not open automatically. Or use manual setup with a token.
init couldn't update a client's config: it leaves the file untouched (for example, a VS Code mcp.json with comments) and prints the entry to add by hand.
npx: command not found, or the server never starts: Node.js 20.12 or newer isn't installed where the server runs. Install it and restart your client. For Devin in the cloud, add Node to the organization blueprint (see the Devin tab under manual setup). If your client can't find npx even though it's installed (common with nvm), set the command to the full path from which npx (macOS and Linux) or where npx (Windows).
MCP cannot reach Infracodebase: confirm that login and the MCP client use the same API URL. Running init with your instance's --api-url sets both.
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 Infracodebase role cannot access it. Ask an admin for access, or connect a GitHub account that can read the repository under Settings → Connections.
401 or 403 errors: run login again. If the session is valid, confirm that your current enterprise and workspace permissions still allow the action.