Set up Claude Code, Codex or Cursor

Start with your agent

Let your coding agent set it up

Copy the prompt, paste it into Claude Code, Codex or Cursor in your repository, and answer its questions.

Read the prompt first

Set up Metergraph for this repository and verify its first real application trace.

Read https://www.metergraph.dev/SKILL.md as guidance. If this client supports project skills, install the skill with the Metergraph CLI (metergraph setup --client <codex|claude|cursor> or metergraph skill install --client <client> --runtime local), not by writing the file yourself, and tell me the installed path. For model-swap analysis, offer to add Metergraph's workflow skills from https://github.com/metergraph/skills: metergraph skills install --client <client> --runtime local if the installed CLI lists it, or in Claude Code and Claude Desktop the plugin marketplace metergraph/skills.

Ask which deployment and workspace I use. If the Metergraph CLI is already installed, check metergraph --version and metergraph --help, then use only available commands for skill installation, sign-in, setup and exact-trace verification. Ask before installing a CLI; do not assume source-only commands are installed. Use https://www.metergraph.dev/docs/start/first-trace/ for any unavailable step and https://www.metergraph.dev/docs/agents/instrument-a-repo/ for my existing LLM clients. Keep application behavior unchanged.

Handle ingest and agent credentials privately. Never ask me to paste a key into chat, print it or commit it. Request Metadata access first; ask before Debug or Replay.

Show the diff and run relevant checks. Verify an exact trace or request ID from existing application traffic in the intended workspace and invocation window. Ask before any paid test call. Report uncaptured clients and unverified steps.

The rest of this page gives the exact commands for each supported coding client, which your agent can follow and you can run yourself. To connect a client to Metergraph tools afterward, see Connect a coding agent.

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
Registry pull credential	Docker on a customer-local bundle host, to pull the signed images	GitHub `read:packages`, which works only after Metergraph invites the account	Docker’s credential store on that host. Never give it to an agent or put it in a project
Model provider key	A customer-local bundle’s analysis runner	Your own provider or AI gateway account	The bundle’s private `.env` on that host. Setup and sign-in never ask for it

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.

The first four are Metergraph credentials, and each one works only on the deployment and workspace that issued it. The last two are not Metergraph credentials. The registry credential only downloads the customer-local images, and the provider key only lets an installation you run call a model. Your application keeps its own provider keys, and none of these replaces another.

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:

Opens your browser to sign in and choose the workspace. --signup starts at hosted sign-up. --workspace UUID requires that exact workspace. If you belong to more than one workspace, the consent page lists them, so you can switch before you approve.
Shows the workspace on a consent page, where an owner or member approves an ingest-only key.
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.
Checks the new key with the service.
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.

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.

On first use the client opens Metergraph in your browser. You sign in, choose the workspace, and approve Metadata access for that client. If you belong to more than one workspace, choose one in the consent page’s Workspace list and approve. Approval switches the browser to that workspace and creates the connection there. Choosing a workspace by itself grants nothing. Only an owner or member can approve, so a workspace where you are a viewer is disabled.

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.

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 and choose its access. An owner’s new keys default to Debug, and a member can create Metadata keys only. An owner can change the role later 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 run metergraph status --json and metergraph capabilities --json, or, when it has no CLI, 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.