Connect an AI assistant

An AI assistant reaches DarkRay through darkray-mcp, a small program the assistant starts by itself. You tell the assistant how to start it once; DarkRay copies the setup for you.

Before you start

• DarkRay is running, with MCP on at the right end of the status bar (see Turn it on).
• The assistant runs on the same computer as DarkRay. The connection never leaves it.

Add DarkRay to Claude Code

1. In DarkRay, choose File › Preferences, then General, and find the MCP card.
2. Click Copy Claude Code command.
3. Paste the command in a terminal and run it.
4. Start a new Claude Code session.

The command adds DarkRay for every project (--scope user). Running DarkRay from its source folder, it looks like this, with your own paths:

claude mcp add darkray --scope user -e PYTHONPATH=Q:\dev\liminal -- Q:\dev\liminal\.venv\Scripts\python.exe -m darkray_bridge.mcp_shim

When a darkray-mcp program sits beside DarkRay’s own, the command names that program instead. [CHECK: the installed layout; the packaged darkray-mcp.exe isn’t built yet]

In Claude Code, DarkRay’s MCP tools show up under the server name darkray, for example mcp__darkray__search_photos.

Add DarkRay to Claude Desktop

1. In DarkRay, choose File › Preferences › General and, on the MCP card, click Copy setup for other assistants.
2. In Claude Desktop, open Settings › Developer and click Edit Config.
3. Paste the entry into the file. If it already has an "mcpServers" section, add the "darkray" entry inside it rather than a second section.
4. Save the file and restart Claude Desktop.

The copied setup looks like this when DarkRay runs from its source folder:

{
  "mcpServers": {
    "darkray": {
      "command": "Q:\\dev\\darkray\\.venv\\Scripts\\python.exe",
      "args": ["-m", "darkray_bridge.mcp_shim"],
      "env": {"PYTHONPATH": "Q:\\dev\\darkray"}
    }
  }
}

Other assistants

Any app that runs MCP servers over standard input and output (stdio) can use the same "mcpServers" entry. darkray-mcp uses only standard MCP: tools, with previews sent as images. It speaks both the older MCP handshake and the 2026-07-28 version.

Check that it works

Ask the assistant something only DarkRay knows:

What does DarkRay show right now?

It should call get_view and describe the mode, the folder or collection, and the selection. In DarkRay, the label beside MCP reads In use, and its tooltip names the assistant. Click In use to open the Console’s MCP card, which lists each request, refusals in red.

If it doesn’t connect

Every MCP tool answers with a sentence saying what is wrong:

The assistant reports	Do this
DarkRay isn’t running; start it.	Start DarkRay.
Assistant control is off: in DarkRay, click MCP at the right end of the status bar.	Click MCP at the right end of the status bar.
DarkRay refused the connection: the token is missing or out of date. …	Try again; if it repeats, restart the assistant.
This version of DarkRay can’t … yet; update DarkRay.	The assistant’s darkray-mcp is newer than DarkRay. Update DarkRay.
DarkRay didn’t answer within 120 s.	DarkRay was busy. Try again, or ask for less at once.

If you turn MCP off and on, or restart DarkRay, the assistant connects again at its next request; you don’t need to restart it.

Caution

While MCP is on, any program on this computer that can read your ~/.darkray folder can work in your catalog. Turn MCP off when you aren’t using it.

Technical details: what darkray-mcp does

darkray-mcp is python -m darkray_bridge.mcp_shim: a stdio MCP server written on the Python standard library, so it starts in a fraction of a second and adds no dependencies. It lists the 23 MCP tools from one table (darkray_bridge/methods.py), and turns each tool call into one request to DarkRay over the bridge, opened at the first call and reopened after DarkRay restarts. DarkRay’s refusals come back as tool results marked as errors, so the assistant can read the sentence and correct itself. A call waits up to 120 s.

It logs to standard error; set DARKRAY_MCP_LOG=DEBUG in its environment for more detail. Legacy clients (MCP 2024-11-05 to 2025-11-25) open with initialize; modern ones (2026-07-28) send the version in each request’s _meta and may call server/discover.