Set up Claude Code, Codex or Cursor

This page gives the exact commands for each supported coding client. Most people should start with the setup prompt in Connect a coding agent and let the agent follow this page.

There are two separate connections, and you can set up either one first:

• Project setup with the metergraph CLI. It signs the project in to one workspace, has a workspace member approve an ingest-only key, writes that key to a private .env file and installs the Metergraph skill for your client. Your application then sends traces with that key.
• MCP connection. Your client calls Metergraph tools in the conversation, so you can ask about usage, routes and traces.

Neither connection reads retained prompts or outputs, or runs a replay, unless it holds the Debug or Replay role.

Credentials, kept apart

Credential	Used by	Scope	Where it lives
Ingest key (mg_...)	Your application, to send traces	ingest only	METERGRAPH_APP_TOKEN in the project’s private .env
CLI sign-in	The metergraph read commands	Metadata (agent:metadata)	Your user’s private config directory, never in the project
MCP browser sign-in	Claude Code, Codex or Cursor	Metadata (agent:metadata) when the client follows the server’s challenge	The client’s own credential store
Coding-agent key	Headless clients, customer-local and Debug or Replay access	Metadata, Debug or Replay, set in Keys	An environment variable the client reads, never a file in the repository

Each coding-agent key has one role, and each role includes the one before it. Metadata reads content-free telemetry and discovers capabilities. Debug adds retained trace content and report evidence. Replay adds bounded replay, which can call a configured model provider and spend money. The CLI always signs in with Metadata only. An MCP client that follows the server’s sign-in challenge requests Metadata. A client configured to request another role, or an older client that requests no scope, can be granted Debug or Replay, and the consent page shows which. To use Debug or Replay deliberately, use a coding-agent key with that role and the keyed setup.

Never paste a key into a chat, a prompt, a committed file or a shared connector.

Set up the project with the CLI

The CLI is published on npm as metergraph-cli. Version 0.2.0 and later, on the latest tag, include the sign-in, setup, verify and read commands. Run it without installing:

npx --yes metergraph-cli@latest --version

Or install the metergraph command:

npm install -g metergraph-cli@latest

It needs Node.js 22 or 24. latest moves when a new release ships, and previews use the next tag. To repeat a setup exactly, run npm view metergraph-cli dist-tags, then pin that version, for example metergraph-cli@<version>.

From the project directory, run setup once with the client that will use the skill:

npx --yes metergraph-cli@latest setup --runtime local --client claude

Use --client codex for Codex and --client cursor for Cursor. Setup:

1. Opens your browser to sign in and choose the workspace. --signup starts at hosted sign-up. --workspace UUID requires that exact workspace.
2. Shows the workspace on a consent page, where an owner or member approves an ingest-only key.
3. Writes METERGRAPH_APP_TOKEN and METERGRAPH_INGEST_URL to .env, makes the file private and adds a .gitignore rule when one is needed. It refuses a tracked env file.
4. Checks the new key with the service.
5. Installs the bundled skill for your client.

--client	Client	Skill file
claude	Claude Code	.claude/skills/metergraph/SKILL.md
codex	Codex	.agents/skills/metergraph/SKILL.md
cursor	Cursor	.cursor/skills/metergraph/SKILL.md

Start or restart the client in the project and check that it lists the metergraph skill. Writing the file does not prove the client has loaded it.

A successful setup means the key was delivered and the project is ready to instrument. It does not mean your application has sent a trace. Follow Send your first trace, then check one exact trace with metergraph verify.

To install or upgrade only the skill, without signing in, run metergraph skill install --client claude --runtime local, or skill update for a newer revision. Both work offline. Neither changes client settings or MCP configuration.

Other deployments

Pass the deployment and its own origin. Never reuse a hosted credential for a customer-operated installation.

Deployment	Setup command additions
Hosted cloud	None. The default origin is https://app.metergraph.dev.
Signed customer-local bundle	--deployment customer-local --url http://localhost:8080 --workspace UUID --confirm-prerequisites
Customer-owned AWS	--deployment byoc --url https://your-installation.example.com --workspace UUID --confirm-prerequisites
Open-source server	--deployment oss --url http://localhost:8787 --workspace UUID --confirm-prerequisites --agent-token-file FILE

Every deployment other than hosted cloud needs its own origin, the exact workspace and --confirm-prerequisites. The open-source route checks the Metadata route with an operator-set agent token, then stops with exit code 6 and oss_ingest_operator_handoff by design: the operator configures ingest with MG_TOKENS.

--confirm-prerequisites records your statement that the signed bundle, registry invitation, local admin and Metadata access are ready. It does not prove them.

Sign-in runs on your own computer

login and setup open a browser on the machine where they run. They refuse cloud runtimes, SSH sessions, cloud development environments and CI before making any request. Run them on your own computer. For a cloud or CI agent, use a coding-agent key instead.

--no-browser prints the sign-in address for you to open on the same machine. With --json, a rerun that needs no new approval succeeds, and one that needs approval stops with exit code 6 so you can rerun it in a terminal.

Check the connection

metergraph status
metergraph capabilities

status reports the bound and verified workspace and the scope. It always reports application_traffic_verified: false, because a signed-in project does not prove your application sends traffic. To sign the project out and ask the service to revoke its grant, run metergraph logout.

Connect the MCP server

The hosted MCP address is https://app.metergraph.dev/v1/agent/mcp. With browser sign-in, the client needs only this address and no header.

Caution

Browser sign-in for MCP clients needs the current hosted service. If sign-in fails with invalid_scope, or no sign-in prompt appears, use a coding-agent key instead.

On first use the client opens Metergraph in your browser. You sign in, choose the workspace, and approve Metadata access for that client.

Claude Code

claude mcp add --transport http --scope project metergraph https://app.metergraph.dev/v1/agent/mcp

--scope project writes .mcp.json in the project, which holds only the address and is safe to commit. Leave it out to keep the server private to you in this project. In Claude Code, run /mcp, choose metergraph and complete sign-in in the browser.

Codex

codex mcp add metergraph --url https://app.metergraph.dev/v1/agent/mcp

Codex can start the browser sign-in as soon as the server is added. If it does not, or you need to sign in again later, run:

codex mcp login metergraph

codex mcp list shows the server and whether you are signed in.

Cursor

Add the server to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "metergraph": {
      "url": "https://app.metergraph.dev/v1/agent/mcp"
    }
  }
}

Cursor asks you to sign in the first time it connects.

What browser sign-in grants

The connection is bound to the one workspace you approved, to that client and to the hosted origin. The consent page shows the role the client asked for. There is no role choice on the consent page, and a connection is never widened silently: a content or replay tool fails on a Metadata connection. For Debug or Replay, use a coding-agent key. An owner can revoke a connection on the Keys page, and the client’s next request then fails until you sign in again.

Use a coding-agent key

Use a key for headless agents, CI, a customer-local or customer-owned AWS installation, or Debug and Replay access. Create a coding-agent key in the intended workspace’s Keys page. New keys start with Metadata; an owner changes the role under Connection access. Keep the key in an environment variable named METERGRAPH_AGENT_TOKEN in the environment that starts the client. See keeping Codex authenticated for a private env file pattern.

Each example uses the hosted address. Replace it with your installation’s address, for example http://127.0.0.1:8080/v1/agent/mcp on a customer-local bundle host.

Claude Code. Add the server to .mcp.json. Claude Code reads the variable when it connects, so the file holds only the variable name:

{
  "mcpServers": {
    "metergraph": {
      "type": "http",
      "url": "https://app.metergraph.dev/v1/agent/mcp",
      "headers": {
        "Authorization": "Bearer ${METERGRAPH_AGENT_TOKEN}"
      }
    }
  }
}

Do not pass the token to claude mcp add --header: your shell expands it and the token is saved in the configuration.

Codex. Codex saves the variable name, not the token:

codex mcp add metergraph --url https://app.metergraph.dev/v1/agent/mcp --bearer-token-env-var METERGRAPH_AGENT_TOKEN

Cursor. Cursor reads the variable when it connects:

{
  "mcpServers": {
    "metergraph": {
      "url": "https://app.metergraph.dev/v1/agent/mcp",
      "headers": {
        "Authorization": "Bearer ${env:METERGRAPH_AGENT_TOKEN}"
      }
    }
  }
}

Restart the client after you set or change the variable. When an owner changes a key’s role, Metergraph replaces the key, so update the saved value.

The open-source server has no Keys page. Its operator sets agent tokens in MG_AGENT_TOKENS, and you use one of those the same way. Its address is http://localhost:8787/v1/agent/mcp on the server host.

localhost always means the computer the client runs on. A client on another computer, or a cloud-hosted connector, cannot reach a local or private-only address.

Check it in the conversation

Ask the agent to call metergraph_get_workspace_context and metergraph_get_capabilities. Setup is complete when it names the workspace you intended and lists the capabilities you expect. If something fails, see Troubleshoot agent setup.

Go deeper

Troubleshoot agent setupCLI exit codes and MCP sign-in, revocation, capability and evidence problems.

Use the MCP serverTool names, privacy classes, deployment capabilities and response bounds.