# MCP server

## Prerequisites

- A Codebahn account
- An MCP-compatible AI assistant (Claude Code, Codex, VS Code with Copilot, or Cursor)

The Codebahn MCP server lets AI assistants work with your repositories, issues, pull requests, and CI through the [Model Context Protocol](https://modelcontextprotocol.io/). Manage code, review diffs, search across repos, and trigger builds, in natural language. The hosted endpoint runs on the same infrastructure as the platform. [Performance numbers](/performance/).

```
https://codebahn.net/mcp
```

## Connect

Add the URL to your MCP client. The first request opens an OAuth flow in your browser. Approve it once and you are set. If you use [two-factor authentication](/docs/two-factor-authentication/), the browser asks for it during this sign-in. The token you get afterwards needs no second factor.

### Claude Code

```bash
claude mcp add --transport http codebahn https://codebahn.net/mcp
```

Run `/mcp` to check status.

### Codex

```bash
codex mcp add codebahn --url https://codebahn.net/mcp
```

### VS Code (Copilot)

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

```json
{
  "servers": {
    "codebahn": {
      "type": "http",
      "url": "https://codebahn.net/mcp"
    }
  }
}
```

### Cursor

Cursor does not yet support Client ID Metadata Documents, so it cannot use the OAuth flow above. Create a personal access token instead: go to **Settings > Applications**, generate a token with repository and organization access set to **All** and each permission category set to **Read and Write**. That matches what the OAuth flow grants; pick narrower permissions if you only need some of the tools.

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

```json
{
  "mcpServers": {
    "codebahn": {
      "url": "https://codebahn.net/mcp",
      "headers": { "Authorization": "Bearer <your personal access token>" }
    }
  }
}
```

## What you can do

Once connected, the assistant has full read and write access to everything your account can reach. Ask it things like:

- "List my repositories on Codebahn"
- "Show the open pull requests on acme/backend"
- "What changed in PR #42?"
- "Create an issue titled 'Fix login redirect' on acme/frontend"
- "Open a pull request from feat/notifications into main on acme/backend"
- "Review the diff on PR #17 and leave comments"
- "Merge PR #42 with squash"
- "Search for usages of `validateToken` across all my repos"
- "Trigger the CI workflow on main"
- "Show the build logs for the latest failed run"
- "Cancel the in-progress CI run"
- "Create a branch called `feat/notifications` from main"
- "Set the `DEPLOY_KEY` CI secret on acme/backend"
- "Cut a release for acme/backend from main"
- "Add a `v1.4.0` tag to the current commit on acme/backend"
- "Create a webhook on acme/backend for push events"
- "Fire a test delivery for the webhook on acme/frontend"
- "Update the default branch on acme/backend to `main`"
- "Require approvals on `main` for acme/frontend"

The server exposes 15 tools across code, branches, issues, pull requests (including reviews), search, CI, releases, secrets and variables, webhooks, repo settings, and branch protection. See the <a href="/docs/mcp/tools/">full tool reference</a> for every tool, its parameters, and which ones are destructive.

## Manage connections

Visit **Settings > Applications** to see authorized OAuth applications and revoke any of them.

## Troubleshooting

| Error | Fix |
|---|---|
| OAuth popup does not appear | Check that your browser allows popups from codebahn.net. |
| HTTP 401 | Token expired or revoked. Remove and re-add the server to trigger a fresh OAuth flow. |
| HTTP 403 | Your account lacks permission for that operation. Check the repository's team settings. |
| `Incompatible auth server` | Your MCP client does not support OAuth discovery. Update to the latest version. |
| `Could not load client metadata from...` / `invalid_client` | Your MCP client must support Client ID Metadata Documents (Claude Code, Codex, and VS Code do). Otherwise, use a personal access token as shown in the Cursor example above. |
| Tool not found | Check the server URL and client config. In Claude Code, `/mcp` lists connected servers. |