MCP MCP server

Set it up

Install the server, create an access key and connect your assistant, in four short steps.

For developers and power users

Setup takes about five minutes. You'll install a small program, create a key in Space, and tell your assistant where to find them.

Before you start

A running Space you can sign in to (you need its web address).
Python 3.11 or newer on your computer.
An MCP-capable assistant: Claude Code, Claude Desktop, Cursor or similar.

1. Install the server

From the project's mcp_server folder, run:

bash

cd mcp_server
pip install -e .

This puts a command called botcircuits-space-mcp on your computer. Use a virtual environment, or pipx install -e ., if you like. With uv, run uv tool install -e ..

2. Create an access key

An access key is a long password that lets the assistant act as you, and you can limit what it may do.

In Space, open Settings › Access keys.
Choose New access key.
Pick the access: All resources, or only what the assistant needs (for example just Skills, Workflows and Tables).
Pick an expiration. Never works, but a limited time is safer.
Copy the key now. It starts with bck_ and is shown once.

3. Add it to your assistant

Claude Code

Run this in a terminal, replacing the key:

bash

claude mcp add botcircuits -e BOTCIRCUITS_ACCESS_KEY=<your-key> -- botcircuits-space-mcp

If Space isn't at http://localhost:8000, add its address:

bash

claude mcp add botcircuits \
  -e BOTCIRCUITS_ACCESS_KEY=<your-key> \
  -e BOTCIRCUITS_API_URL=https://copilot.example.com \
  -- botcircuits-space-mcp

Claude Desktop, Cursor and others

Add this to the assistant's MCP settings file (for Claude Desktop on a Mac this is ~/Library/Application Support/Claude/claude_desktop_config.json, and for Cursor it's .cursor/mcp.json):

json

{
  "mcpServers": {
    "botcircuits": {
      "command": "botcircuits-space-mcp",
      "env": {
        "BOTCIRCUITS_ACCESS_KEY": "<your-key>",
        "BOTCIRCUITS_API_URL": "http://localhost:8000"
      }
    }
  }
}

If the assistant can't find the command, use its full path. Find it with which botcircuits-space-mcp. Then restart the assistant.

4. Check that it works

Ask your assistant:

Try asking

Who am I signed in as in the Copilot?

It should call a tool named auth_me and tell you your name. Then try:

Try asking

List my skills.

Settings

You can set these as environment values next to the key.

Setting	Default	What it does
`BOTCIRCUITS_ACCESS_KEY`	required	Your access key. The server won't start without it.
`BOTCIRCUITS_API_URL`	`http://localhost:8000`	Where Space lives. Use `https` for anything except your own computer, because the key travels with every request.
`BOTCIRCUITS_WORKSPACE`	none	Limits file uploads and saves to one folder. Recommended.
`BOTCIRCUITS_TIMEOUT`	`120`	Seconds to wait per request.
`BOTCIRCUITS_CHAT_TIMEOUT`	`300`	Seconds a chat message waits for the answer. The copilot keeps going afterwards.
`BOTCIRCUITS_CHAT_POLL_SECONDS`	`1`	How often to check a chat turn.
`BOTCIRCUITS_MAX_OUTPUT_CHARS`	`20000`	Longest result passed back to the assistant.

Settings can also be put in a .env file in the folder you run it from.