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: give your assistant a token and point it at the server. 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.

Create an access token

Go to Settings > Applications on your Codebahn instance and create a token. Pick scopes for what the assistant should do:

What you want	Scopes
Read code, browse repos	read:repository
Create files, branches, PRs, trigger CI	write:repository
Read and create issues	read:issue, write:issue
Full access (recommended)	write:repository, write:issue, write:user

Copy the token after creation. You will not see it again.

When a call fails for lack of a scope, the error names the scope to add.

Configure your client

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

The token is passed via the CODEBAHN_TOKEN environment variable. All MCP clients support setting env vars in their config, which keeps the token out of command-line arguments. You can also pass --token directly if you prefer.

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"],
      "env": {
        "CODEBAHN_TOKEN": "your-token"
      }
    }
  }
}

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"],
      "env": {
        "CODEBAHN_TOKEN": "your-token"
      }
    }
  }
}

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"],
      "env": {
        "CODEBAHN_TOKEN": "your-token"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "codebahn": {
      "command": "/path/to/codebahn",
      "args": ["serve"],
      "env": {
        "CODEBAHN_TOKEN": "your-token"
      }
    }
  }
}

Shell environment

You can also export the token in your shell instead of setting it per-client:

export CODEBAHN_TOKEN=your-token

Then drop the env block from the config. The server reads the token from the environment.

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 the instance.
• 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
--token or CODEBAHN_TOKEN is required	No token configured. Set CODEBAHN_TOKEN in your client’s env block, export it in your shell, or pass --token.
HTTP 401	Token is invalid or expired. Create a new one at Settings > Applications.
HTTP 403	Token is missing a scope for that operation. Check the scope table above and reissue.
Tool not found	Check the binary path and client config. In Claude Code, /mcp lists connected servers.