Docs / MCP

MCP setup

One command wires Beryl into your coding agent. Any client that speaks MCP works, listed here or not.

Set up your agent with beryl mcp

npx @beryl-so/cli@latest init

Signs you in, wires the beryl MCP server, and installs the beryl-test skill. It asks which agent to wire, or pass the flag for yours:

npx @beryl-so/cli@latest init --claude

Manual setup

For a client init does not wire yet. Start with init anyway: it does everything except touch your client's config.

Run init, pick Other

npx @beryl-so/cli@latest init

Signs you in and installs the beryl-test skill.

No browser on the machine? Create a token at beryl.so → Account → Personal access tokens and set BERYL_API_KEY before you start your client.

Add the server to your config

Name

beryl

Transport

stdio (local process)

Command

npx

Args

-y @beryl-so/cli@latest mcp

Most clients use this shape:

{
  "mcpServers": {
    "beryl": {
      "command": "npx",
      "args": ["-y", "@beryl-so/cli@latest", "mcp"]
    }
  }
}

Some clients call that top-level key servers or mcp, or want a type field. Check your client's docs for the wrapper. The values inside are the same everywhere, and your client spawns the command, so you never run it.

Restart and check

Restart your client, then ask it to call whoami. Your agent reads the test guide itself with the guide tool. Needs Node 20.19 or newer.

Troubleshooting

No beryl tools

MCP config is read at startup. Restart the client; for Claude Desktop quit the app, not just the window.

Tools 401

Run beryl login. No reconnect needed: the server re-reads it. For BERYL_API_KEY, restart the client so it inherits the variable.

Command not found

npx needs Node 20.19+ on the PATH your client starts with. Check node --version.

Still stuck, or using an agent init does not wire yet? Support has the common fixes, and telling us which agent you use is how it gets added.