Connect an AI assistant

The codebahn binary runs as an MCP server so AI coding assistants can work with your repositories, issues, pull requests, and CI. It exposes 51 tools across code, branches, issues, pull requests (including reviews), and CI.

This is step six of your first 30 days. By now you have pushed a repo and set up CI. Next: log in with the CLI and point your assistant at it. Setup below covers Claude Code, Claude Desktop, VS Code (Copilot), and Cursor. The same binary is also a command-line tool if you prefer the terminal.

Install the binary

Download a pre-built release for your OS and architecture from the releases page.

To build from source instead (MIT-licensed):

git clone https://codeberg.org/codebahn/codebahn.git
cd codebahn
go build -o codebahn .

Move the binary somewhere on your PATH, for example ~/.local/bin/codebahn.

Log in

codebahn auth login

This opens your browser for OAuth authorization. After you approve, the CLI saves your tokens to ~/.config/codebahn/config.json. Tokens refresh automatically; you should not need to log in again unless you revoke access.

The MCP server reads from the same config file, so no token needs to appear in your MCP client config.

Configure your client

Each client stores MCP config in a different file. Replace /path/to/codebahn with the binary path. The server defaults to stdio transport; sse and http are also available via --transport.

Claude Code

Create .mcp.json in your project root, or ~/.claude/mcp.json for global config:

{
  "mcpServers": {
    "codebahn": {
      "type": "stdio",
      "command": "/path/to/codebahn",
      "args": ["serve"]
    }
  }
}

Start Claude Code in the same directory. It prompts you to approve the server on first launch. Run /mcp to check status.

Claude Desktop

Open Settings > Developer > Edit Config and add:

{
  "mcpServers": {
    "codebahn": {
      "command": "/path/to/codebahn",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop after saving.

VS Code (Copilot)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "codebahn": {
      "type": "stdio",
      "command": "/path/to/codebahn",
      "args": ["serve"]
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codebahn": {
      "command": "/path/to/codebahn",
      "args": ["serve"]
    }
  }
}

CI and headless environments

For environments where you cannot open a browser, set a personal access token as an environment variable:

export CODEBAHN_TOKEN=your-token

Create the token under Settings > Applications in your Codebahn account. Add CODEBAHN_TOKEN to your MCP client’s env block or CI secrets.

Caution

If your .mcp.json contains a token, add it to .gitignore.

The server connects to codebahn.net by default. Override with --url for local development.

What the assistant can do

Once connected, the assistant works against your repos through the Codebahn API. The server translates its tool calls into API requests and returns JSON.

• Code and repos: list repos, browse trees, read files, create and update files, manage branches, view commit history.
• Issues: create, update, close, comment, add and remove labels.
• Pull requests: open, review diffs, list changed files, merge; request reviewers, approve, dismiss reviews.
• Search: find code, repositories, and issues across your account.
• CI: trigger runs, check status, read logs, cancel. Works with both hosted runners and BYO runners.

Commits the assistant creates are signed and verify against the Codebahn signing key (signer noreply@codebahn.net).

Verify the connection

Ask the assistant to list your repositories:

List my repositories on Codebahn

In Claude Code, /mcp shows server status directly.

Assistant-triggered CI runs draw on the same plan minutes as any other build. See billing for limits and what happens at the cap.

Troubleshooting

Error	Fix
not logged in; run 'codebahn auth login'	No saved tokens and no CODEBAHN_TOKEN set. Run codebahn auth login in your terminal.
token refresh failed	Saved tokens expired or were revoked. Run codebahn auth login again.
HTTP 401	Token is invalid. Run codebahn auth login to re-authenticate, or reissue your CODEBAHN_TOKEN.
HTTP 403	Token is missing a scope for that operation. OAuth tokens have full access. If using CODEBAHN_TOKEN, check the scope table in Settings > Applications.
Tool not found	Check the binary path and client config. In Claude Code, /mcp lists connected servers.