CLI and MCP server

Two tools, one key

Two tools for your own machine, both over API v2 with one of your keys: bidi, a command line for terminals and scripts, and an MCP server that hands the same operations to an AI client such as Claude Desktop. Both read the key from the environment only; neither writes it to disk or prints it.

1. Install and set your key

From a checkout of the repository, with Python 3.10 or newer, install both packages. The tools read BIDI_API_KEY and BIDI_API_URL (by default https://www.bidii.ai) and nothing else, so there is no config file to leak. Plain http is refused except for localhost: the key never crosses a network in clear text.

pip install -e cli/ -e mcp/

export BIDI_API_KEY=bidi_sk_YOUR_KEY        # macOS and Linux
$env:BIDI_API_KEY = "bidi_sk_YOUR_KEY"      # PowerShell
bidi whoami

2. Commands

Every command takes --json for scripts. Exit code 0 means done, 1 that the API refused (the message names the error code and the request id), 2 a usage or settings problem.

bidi agents list
bidi agents show AGENT_ID
bidi sources list AGENT_ID
bidi sources push AGENT_ID ./docs --dry-run
bidi sources pull AGENT_ID ./docs
bidi chat AGENT_ID "Are you open on Friday?"
bidi logs tail AGENT_ID --follow
bidi leads export --status new -o leads.csv

The scopes each command needs

bidi whoami works with any key. agents and sources list and pull need agents:read, sources push needs sources:write, chat needs chat, logs tail needs conversations:read and leads export needs leads:read. The MCP server's tools need the same scopes as the commands they mirror.

3. Keep an agent's knowledge in a folder

bidi sources push turns each .md, .markdown and .txt file into a text source named by its path, and uploads only the files whose SHA-256 differs from the content_sha256 the API reports for the source of the same name. Run it after every change to your docs: unchanged files cost nothing. bidi sources pull writes the agent's text sources into a folder and keeps any file you changed locally unless you pass --force.

$ bidi sources push AGENT_ID ./docs
unchanged    opening-hours
updated      branches/دبي
added        parking
2 uploaded, 1 unchanged.

4. Chat and follow conversations

bidi chat prints the answer as it streams in and puts the conversation id on standard error, so you can pipe the answer alone. bidi logs tail --follow prints new messages from every channel as they arrive, and bidi leads export writes a CSV that Excel opens with its Arabic intact, with any cell that starts like a formula made safe.

$ bidi chat AGENT_ID "ما هي ساعات العمل؟"
نفتح من السبت إلى الخميس، من 9 صباحاً حتى 6 مساءً.
[conversation 0c9e7d2a-1f4b-4a63-8e2d-7b5f6a1c2d3e] outcome: answered

5. Connect an AI client over MCP

bidi-mcp is an MCP server over stdio, built on the official MCP Python SDK. It offers eight tools: list_agents, get_agent, list_sources, read_source, push_source, chat, recent_messages and export_leads. Every input is checked against its schema before a request is made.

{
  "mcpServers": {
    "bidi": {
      "command": "bidi-mcp",
      "env": { "BIDI_API_KEY": "bidi_sk_YOUR_KEY" }
    }
  }
}

Your MCP client keeps this entry in its own settings file on your computer: use a key made only for it, with the scopes its tools need, and revoke it in Settings > Developers if the file is shared.

What visitors, your agents and your team wrote comes back as data, never as instructions: those results are marked untrusted with a notice that says so, and the tool descriptions say it too. A visitor who types "ignore your instructions" into the chat gives the client's model something to read, not something to do. Give the key only the scopes the tools you use need.

Language and encoding

The tools speak English in the terminal: a terminal cannot be relied on to join Arabic letters and order mixed lines, and the API's error codes are English anyway. Your content is UTF-8 end to end, also through pipes on Windows, so Arabic names, knowledge, conversations and leads arrive exactly as they were written. Control characters inside conversation text are dropped before printing, so nobody can drive your terminal through the chat.