# Add the DiceyTable MCP server to Claude Code

> Run one claude mcp add command to give Claude Code the DiceyTable tools, pick a scope for one project or all of them, and check it with claude mcp list.

- Question: How do I add the DiceyTable MCP server to Claude Code?
- Source: https://diceytable.com/docs/ai-agents/setup/claude-code
- Last verified: 2026-10-09

Run `claude mcp add diceytable -- npx -y @diceytable/mcp-bridge@1` in a terminal, inside your project folder. From then on, Claude Code starts the DiceyTable bridge for you whenever it needs it.

The bridge is the small program that links Claude to a DiceyTable tab in your browser. It comes from npm, so there is nothing to download by hand. This page assumes you have saved a key with `login`, as [Install the DiceyTable MCP bridge](https://diceytable.com/docs/ai-agents/setup/install) shows.

## What you'll need

- **Claude Code**, signed in. Run `claude --version` to check.
- **Node.js 20.19 or newer.** Run `node --version` to check. Claude Code uses the same `npx` you do.
- **A saved key.** Run `npx -y @diceytable/mcp-bridge@1 status`. It should name your account and your key. No key yet? [Create an API key for your AI agent](https://diceytable.com/docs/ai-agents/setup/api-keys) first.

## Step 1: Add the server

Open a terminal in your project folder and run:

```sh
claude mcp add diceytable -- npx -y @diceytable/mcp-bridge@1
```

Everything after `--` is the command Claude Code runs to start the bridge. Claude Code prints an `Added` line when it has saved the entry.

Keep the name `diceytable`. Claude Code shows each tool as `mcp__diceytable__<tool>`, for example `mcp__diceytable__session_connect`. The [instructions for your AI agent](https://diceytable.com/docs/ai-agents/workflows/agent-instructions) use that name too.

## Should it work in one project or all of them?

Claude Code calls this the **scope**. The command above uses the default, `local`, so DiceyTable only shows up in this one project.

To use DiceyTable in every project on this computer, add `--scope user`:

```sh
claude mcp add diceytable --scope user -- npx -y @diceytable/mcp-bridge@1
```

Both scopes live in your own `~/.claude.json` file. That file belongs to you and is never part of a repository.

## How do I share the setup with my team?

Use the `project` scope. Commit a file named `.mcp.json` at the root of your repository:

```json
{
  "mcpServers": {
    "diceytable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@diceytable/mcp-bridge@1"]
    }
  }
}
```

This file holds no key, so it is safe to commit. Each person saves their own key with `login`. The first time someone opens the project, Claude Code asks them to approve the server.

## Step 2: Check the connection

Run:

```sh
claude mcp list
```

You should see `diceytable` with `✔ Connected`. The very first check can say `✘ Failed to connect` while `npx` downloads the bridge. Wait a moment and run it again.

Inside a Claude Code session, type `/mcp` to see the same status. **Connected** means Claude Code can start the bridge. Your key gets checked later, when the agent connects to DiceyTable.

## Step 3: Connect a DiceyTable tab

Ask Claude to "connect to DiceyTable". It replies with a pairing code. Type that code into a DiceyTable tab, as [Pair a DiceyTable tab with your agent](https://diceytable.com/docs/ai-agents/setup/pairing) shows. Then [check your agent is connected](https://diceytable.com/docs/ai-agents/setup/verify).

## Local files and other folders

The bridge only reads and writes local files inside allowed folders. Claude Code usually starts it in your project folder, and that folder is always allowed. To let the agent import art from somewhere else, add `--allow-dir` after the package name:

```sh
claude mcp add diceytable -- npx -y @diceytable/mcp-bridge@1 --allow-dir /path/to/card-art
```

[Which local files an agent can read](https://diceytable.com/docs/ai-agents/concepts/local-file-access) explains the rules.

## Using an environment variable instead of login

`login` is the easiest choice. If you would rather keep the key in an environment variable, add an `env` line to the `diceytable` entry in `.mcp.json`. It names the variable and never holds the key itself:

```json
"env": { "DICEYTABLE_TOKEN": "${DICEYTABLE_TOKEN}" }
```

Claude Code fills in `${DICEYTABLE_TOKEN}` from your shell when it starts the bridge.

> **⚠ Never put a key in a shared config.** Don't combine `--env` with `--scope project`. That writes the key into `.mcp.json`, which you might commit. A committed key is a published key.

## If it doesn't work

- **Connection timed out at startup.** The first `npx` download can take longer than Claude Code's 30-second limit. Start Claude Code with a longer one: `MCP_TIMEOUT=60000 claude`, or `$env:MCP_TIMEOUT = "60000"; claude` in PowerShell.
- **The bridge won't start on Windows.** Wrap the command: `claude mcp add diceytable -- cmd /c npx -y @diceytable/mcp-bridge@1`.
- **You ran `login` after starting Claude Code.** The bridge reads the key when it starts. Reconnect the server from `/mcp`.

For anything else, run `npx -y @diceytable/mcp-bridge@1 doctor`, then see [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection).

To remove the server later, run `claude mcp remove diceytable`. [Disconnect, revoke or remove the agent](https://diceytable.com/docs/ai-agents/setup/uninstall) covers the rest.

## Next steps

- [Pair a DiceyTable tab with your agent](https://diceytable.com/docs/ai-agents/setup/pairing): type the code and read the consent dialog.
- [Check your agent is connected](https://diceytable.com/docs/ai-agents/setup/verify): three quick calls that prove it all works.
- [Instructions to give your AI agent](https://diceytable.com/docs/ai-agents/workflows/agent-instructions): a starting prompt and a `CLAUDE.md` snippet.