Connect an AI client

What it does today

The server is bitling-mcp, a program that ships next to the Bitling desktop app. Your AI tool starts it when it needs it and talks to it over standard input and output. Nothing listens on the network. It works with your local Bitling library: it reads your practice context and can add the few practice records listed below. It has no access to the rest of your files and can't run commands.

It offers five read-only resources your AI tool can pull in. "Current" means the Bitling project folder your AI tool is running in, or, outside one, the attempt you started most recently that's still in progress.

Current problem practice://current/problem

The problem's statement as plain text: description, constraints, notes, examples, and tags. Never starter code, your code, or the page's HTML.

Current practice session practice://current/session

The attempt in progress on that problem, its recent events (what happened and when), the hints it has used, and how earlier attempts went. During a blind reattempt it counts only the blind attempt and says earlier ones are hidden. While a practice session is open, it shows the rules you set for it, and when those hide earlier attempts it counts only the attempt in progress.

Current test status practice://current/test-status

The test runs Bitling picked up for the attempt in progress, newest first, with passed, failed, and skipped counts. Until you turn on test pickup for the project (below) and run your tests, it answers that none are recorded.

Coach profile practice://current/coach

The coach you picked in Settings, the highest hint level it allows (and a lower one set by a practice session you have open), and how to give a hint at each of those levels. It answers even before you've imported a problem.

Problem history practice://history/problem/{id}

Past attempts at one problem, newest first. While a blind reattempt of it is in progress, or an open practice session hides earlier attempts, only the attempt in progress. The other three give each problem's history link.

It also offers six tools. Three read the same things as the resources above. The other three are the only way the server changes your library, and each one works only on the attempt in progress on the current problem. They never start an attempt, never touch another problem's attempt, and never change a finished one.

Current problem get_current_problem

Reads the same thing as the current problem resource.

Attempt context get_attempt_context

Reads the same thing as the current practice session resource, including how many hints this attempt has used and the highest hint level it can take next. The count reads the attempt's newest 5000 events; for an attempt with more, it says the number may be low.

Test summary get_test_summary

Reads the same thing as the current test status resource.

Record a hint record_hint

Notes that your AI tool gave you a hint, and at what level: 0, a question back to you, through 5, a full explanation. Levels unlock one at a time: the first hint on an attempt is level 0, and each one can be at most one level above the highest so far. The coach you pick in Settings sets the highest level, and level 5 is refused unless you unlock it there (see below). A practice session you have open can keep hints lower than your coach, never higher. A refused level isn't recorded, and your AI tool is told the highest level it can give. It stores the level and, optionally, a one-line note of up to 500 characters (an emoji built from several, like a flag, counts as each of them).

Record a reflection record_reflection

Saves a short reflection on the attempt, up to 1000 characters.

Complete the attempt complete_attempt

Finishes the attempt as solved, partial, abandoned, or reviewed. A finished attempt is never changed, so asking twice does nothing.

The server asks your AI tool to record each hint before giving it, so your history shows how much help you had, and tells it how to give a hint at the level it recorded. It also asks your AI tool never to go past the last level it recorded, even when you ask for more, and to keep hints warm, never counting them against you. Whether it does is up to the AI tool: the hint levels limit what can be recorded, not what an AI tool that skips recording says. Test connection in the app tells you how many resources and tools your version offers.

Choosing a coach

In the desktop app, go to Settings and find Coach. The coach you pick there decides how your AI tool coaches you and how far its hints can go.

• DSA Tutor: hints up to level 3 , the default.
• Interview Coach: hints up to level 1 (preview).
• Reviewer: hints up to level 4 (preview).
• Mock Interviewer: hints up to level 0 (preview).

• The preview coaches appear once you tick Show preview coaches. Turning it off again moves you back to the DSA Tutor.
• Highest hint level lets you pick any level from 0 to 4 instead of the coach's own. Picking a different coach starts it at its own level.
• Level 5, a full explanation, stays locked until you tick Unlock full explanations (level 5). Hints can then go up to level 5, still one level at a time. Picking a different coach locks it again.

Only the app changes these. The server reads them from your settings file for each hint, and each time your AI tool reads the coach, the practice session or the prompt, so a change applies right away. Nothing your AI tool sends can change them: asking for more in a chat doesn't unlock anything. If your settings file can't be read, the server uses the DSA Tutor with level 5 locked.

The server also offers one prompt, coach. Clients that support prompts show it as a command. It starts coaching on the current problem as the coach you picked, and it takes no options.

Rules for a practice session

When you plan a session on the Practice screen, Coach rules sets how your AI coach helps while that session is open.

• Hint limit keeps hints to a level from 0 to 4, or leaves it at Your coach's limit. A session can only keep hints lower than your coach, never higher: the limit is whichever of the two is lower, and level 5 stays locked under any session limit, even if you unlocked it in Settings.
• Hide earlier attempts from the coach shows your AI tool only the attempt you're on, like a blind reattempt.
• Hide the problem's source link from the coach leaves out the link to the problem's page.

Interview Simulation starts with hints up to level 1 and earlier attempts hidden; the other modes start with none of these. You can change any of them before you start, and while the session runs with Change rules. The rules apply to every hint while the session is open, paused included, whichever problem your AI tool is on, and stop once the session is finished.

A hint above the session's limit is refused and not recorded. Your AI tool is told the highest level it can give and that only you can change the limit, on the Practice screen, and the server notes the refusal in its log, which your AI tool may keep with its MCP logs. Nothing your AI tool sends can change a session's rules.

Test results

Bitling never runs your tests. When you run them the way you normally do, they write a report file, and the desktop app reads that file, but only in projects you turn this on for. In the desktop app's Library, tick Pick up test results on the problem. It applies to the project of the attempt in progress, or else the problem's newest project. Nothing from before you turned it on is picked up.

Kotlin and Java (Gradle) build/test-results/test/*.xml

Gradle writes these itself on every gradle test.

Python (pytest) test-results/pytest.xml

pytest writes it because the project's pytest.ini asks for it: addopts = --junitxml=test-results/pytest.xml

TypeScript and JavaScript (Vitest) test-results/vitest.json

npm test writes it: the project's package.json test script is vitest run --reporter=default --reporter=json --outputFile.json=test-results/vitest.json

A picked-up run counts toward the attempt that was in progress when the tests ran, and practice://current/test-status shows it to your AI tool. The Library row shows the latest run's counts.

• Rust / Cargo, Go / go test projects aren't supported yet: cargo test and go test don't write a report file.
• Projects created before this existed may not ask for the report. Their Library row shows the exact line to add or change in pytest.ini or package.json. Bitling doesn't edit your files.
• pytest writes its report relative to the folder you run it from, so run it from the project folder. Running npx vitest directly or from an editor's test panel skips the npm test script, and those runs aren't picked up.
• The desktop app looks every 3 seconds while it's running, including in the tray with its window closed. If it isn't running, the latest report is picked up when it starts.

1. Copy the server's path

Open the Bitling desktop app, go to Settings, and find Connect an AI client. It shows the full path to bitling-mcp for your install. Click Copy path. On a Mac with Bitling in Applications, it looks like /Applications/Bitling.app/Contents/MacOS/bitling-mcp.

Test connection starts the server the same way your AI tool will, with no arguments, and checks that it answers. It doesn't change anything in your AI tool.

• On a Mac, run Bitling from your Applications folder first. If it's running from the disk image or from Downloads, macOS gives it a temporary path that changes, and the panel says so.
• With the AppImage on Linux, the path is a copy Bitling keeps at ~/.local/share/bitling/bin/bitling-mcp, because the AppImage's own path changes every time it runs. Bitling refreshes the copy each time it starts, so updates reach your AI tool too.

2. Add it to your AI client

Bitling never edits your AI tool's settings files. You add it yourself, once. The snippets below use /path/to/bitling-mcp; the app's Settings panel shows the same snippets with your real path filled in and quoted for your system, each with a copy button.

Claude Code

Run this once in a terminal. It adds Bitling for all your projects:

>_ claude mcp add --scope user bitling /path/to/bitling-mcp

Then run /mcp inside Claude Code to check that bitling is connected.

Codex

Run this once in a terminal:

>_ codex mcp add bitling /path/to/bitling-mcp

Or add this to ~/.codex/config.toml yourself:

[mcp_servers.bitling]
command = "/path/to/bitling-mcp"

Cursor

Add this to ~/.cursor/mcp.json. If the file already has "mcpServers", add just the "bitling" entry inside it:

{
  "mcpServers": {
    "bitling": {
      "command": "/path/to/bitling-mcp"
    }
  }
}

Other MCP clients

Most MCP clients accept the same "mcpServers" entry as Cursor. Anything else needs just three facts:

• it's a stdio server,
• the command is the path from Settings, and
• it takes no arguments.

On Windows, config files live under %USERPROFILE% instead of ~, and the path ends in .exe. The app shows each command twice, once for PowerShell and once for Command Prompt, because each shell needs its own quoting. If your path contains a %, a !, or a quote, it shows only the PowerShell one, since Command Prompt can't pass that safely. Copy the snippets from the app so the quoting and backslashes come out right.

If the connection test fails

The MCP server didn't answer in time.

It started but stayed quiet for 10 seconds. Try again; if it keeps happening, reinstall Bitling.

The MCP server started but didn't answer.

It exited without replying. Reinstalling Bitling usually fixes it.

Bitling's installation is incomplete: its MCP server is missing. Reinstalling Bitling puts it back.

The server file is missing from your install, for example after an interrupted update. With the AppImage, Bitling also removes its old copy so nothing runs an outdated server.

That program answered, but not like Bitling's MCP server.

Something else is sitting where the server should be. Reinstalling Bitling replaces it.

If the test passes but your AI tool can't connect, check that the path in its settings matches the one in Bitling exactly. Moving or reinstalling Bitling can change it.