Docs

Connect your agent to Bilg

Bilg is an MCP server. Any client that speaks MCP over Streamable HTTP can read and write your projects: Claude Code, Claude Desktop, claude.ai, Cursor, Windsurf, Codex CLI, Cline and others. Setup takes one API key and one config entry, or one prompt if you let your agent do it.

Create an account and a project

Sign up (free, no card), then create your first project in the onboarding wizard. Every project gets a short code such as BLG; epics, tasks and questions are keyed from it (BLG-E15), so you and your agent can refer to work by name.

Get credentials

Coding agents(Claude Code, Cursor, Windsurf, Codex CLI, Cline) use an API key: Settings → API keys → Create. Bind the key to a default project so tool calls don't need a projectName argument. The key is shown once.

Claude Desktop and claude.ai use OAuth instead: add a custom connector with the connector URL below and approve the sign-in prompt. No key needed.

Add the server

Replace blg_YOUR_KEY with your key. The AI-assisted tab is a prompt you paste into your agent; it applies the right config for its own client and verifies the connection. The Manual tab has the same config for you to apply by hand.

Paste this into your coding agent. It adds the server for whichever MCP client it runs in, keeps the key in that client's config only, and verifies the connection with whoami.

Setup prompt

Connect this environment to my Bilg workspace over MCP and verify the connection. Bilg is a shared knowledge base and epic board that my agents read and write through MCP.

MCP endpoint: https://mcp.bilgai.com/mcp
Transport: Streamable HTTP. Server name: bilg. Auth: HTTP header `Authorization: Bearer blg_YOUR_KEY`

1. Work out which MCP client you are running in (Claude Code, Cursor, Windsurf, Codex CLI, Cline, another) and add the server the way that client expects.
   Claude Code:
   claude mcp add --transport http bilg https://mcp.bilgai.com/mcp --header "Authorization: Bearer blg_YOUR_KEY"
   Clients configured with an mcpServers JSON file:
   {
     "mcpServers": {
       "bilg": {
         "type": "http",
         "url": "https://mcp.bilgai.com/mcp",
         "headers": {
           "Authorization": "Bearer blg_YOUR_KEY"
         }
       }
     }
   }
2. Write the key only into that config file. Do not echo it back to me, do not paste it into other files, do not commit it.
3. Reload MCP servers if your client needs it. Then call the `whoami` tool, then `list_projects`. Tell me who I am signed in as and which projects you can see.
4. If a call fails with 401, the key is wrong or revoked: ask me for a new one from Settings → API keys. On 404 or connection refused, re-check the URL.
5. Read the server instructions returned at initialize. They describe how epics, tasks, questions and documents are meant to be used. Follow them from now on.

Once connected, this second prompt moves your repository's context into Bilg: docs, epics, tasks, open questions and decisions. Replace the project name first.

First-day prompt

Move this repository's context into my Bilg project "<PROJECT NAME>" so you and my teammates' agents share it next session. Use the Bilg MCP tools.

1. Call `list_projects` and pick the project I named. If it does not exist, stop and ask me to create it in the Bilg web UI.
2. Read the README, docs/ and any spec or ADR files. Upload the ones that describe what the product is and how it works with `create_document`, keeping the original file names under a `docs` folder. Skip generated files, lockfiles and anything that looks like a secret.
3. From README, TODO lists, backlog files or issues you find, draft the current work as epics with `create_epic`: one epic per coherent piece of work, two-line description each. Under each, add concrete steps with `create_task`. Do not invent priority or size.
4. Anything still undecided goes in with `create_open_question`, not as a task.
5. Decisions already made (framework choices, why X and not Y) go in with `create_decision`, with the reasoning.
6. Finish with a short summary: documents uploaded, epics, tasks and questions created with their keys, and anything you were unsure about.

Verify

Ask your agent to call whoami. It should answer with your name and plan. Then list_projects should show the project you created. A 401 means the key is wrong or revoked; a connection error means the URL is wrong.

At initialize the server returns instructions that explain how epics, tasks, questions and documents are meant to be used. Your agent reads them automatically; you can add your own team rules per project under Project → Agent rules.

What your agent can do

Search your documents semantically and read them in full.
Create and update documents, epics, tasks, open questions and decisions.
Move tasks and epics through their lifecycle as work gets done.
Leave a handoff note for a teammate's agent, and pick up notes left for yours.

Two things are reserved for humans in the web UI and refused to agents by the server: marking an epic deployed, and permanently deleting work items.

VS Code

The Bilg extension shows the same board, docs, notifications and handoffs inside VS Code. It uses the same API key. Cursor, Windsurf and other forks install it from Open VSX.

Something not working?

Open an issue on the feedback tracker with the client you use and the tool call that failed. Support and status links are in the footer.