Connecting Claude Code
Add OpsDash to Claude Code with a .mcp.json file that reads your token from an environment variable, so the token never goes in your code.
Claude Code connects to OpsDash's MCP server directly over HTTP. Keep the token in an environment variable, not in a file you might commit.
What you need first
- Claude Code installed.
- A staff connection token (choose the Cursor kind) and the MCP address from Settings › Agents.
1. Put the token in an environment variable
Call it OPSDASH_MCP_TOKEN.
- Windows: open Edit environment variables for your account, add a new user variable
OPSDASH_MCP_TOKENwith the token as its value, then open a new terminal. - Mac or Linux: add
export OPSDASH_MCP_TOKEN="your-token"to your shell profile (for example~/.zshrc), then open a new terminal.
2. Add a .mcp.json file
In the folder you run Claude Code from, create .mcp.json:
{
"mcpServers": {
"opsdash": {
"type": "http",
"url": "https://www.opsdash.io/api/mcp",
"headers": {
"Authorization": "Bearer ${OPSDASH_MCP_TOKEN:-}"
}
}
}
}
Change the address if your OpsDash isn't opsdash.io. ${OPSDASH_MCP_TOKEN:-} is filled in from the environment variable when Claude Code starts (and left empty, rather than failing, if it isn't set). The file is safe to commit: it holds no secret.
3. Start Claude Code
Start Claude Code from that folder. The first time, it asks whether to trust the project's MCP servers: approve opsdash. Run /mcp to see it connected and list its tools, then ask "Who am I in OpsDash?" to check.
Just for you, without a file
To add OpsDash for yourself only, run this in a terminal (it reads the variable when you run it, so the token is saved in your Claude Code settings rather than a project file):
claude mcp add --transport http opsdash https://www.opsdash.io/api/mcp --header "Authorization: Bearer $OPSDASH_MCP_TOKEN"
Troubleshooting
- opsdash shows as failed in /mcp: the variable wasn't set when Claude Code started. Open a new terminal (so it picks up the variable) and start Claude Code again.
- 401 Unauthorized: the token is wrong, or the connection is off or removed.
- 403 "no longer an owner or admin": the connection's creator left or changed role; make a new connection.
- The tools look out of date: OpsDash tells clients when its tool list changes; run
/mcpto reconnect if needed.
Settings in OpsDash
These open in OpsDash. You’ll be asked to sign in first if you aren’t already.
Related articles
- Creating a staff connectionMake a connection and token in Settings › Agents for an AI assistant to use OpsDash's MCP server, and manage the connections you have.
- Connecting Claude DesktopAdd OpsDash to the Claude Desktop app with your connection token, so Claude can read and update your projects, tasks, time and invoices.
- Revoking connections and keeping tokens safeHow to store agent tokens safely, switch connections off or remove them, and what to do if a token leaks.