Connect a coding agent
Start with your agent
Section titled “Start with your agent”Open Codex or Claude Desktop and paste this prompt:
Help me connect Metergraph to this agent. Readhttps://www.metergraph.dev/SKILL.md. If you cannot, ask me to paste it. Firstask which deployment I use: hosted cloud, the signed customer-local bundle,customer-owned AWS, or the open-source self-hosted server, and which workspace.Guide account creation, invitation, sign-in, or installation as appropriate. Ifyou can run shell commands here, use the metergraph CLI first, throughnpx --yes metergraph-cli@latest when it is not installed. Follow SKILL.md's CLIpath for this runtime, pointing it at my installation and workspace with --urland --workspace, then run metergraph status --json andmetergraph capabilities --json and check they name that workspace. Only if theCLI cannot run here or does not support this deployment, choose the supportedMCP setup for this client and runtime, then callmetergraph_get_workspace_context and metergraph_get_capabilities. Give me oneaction at a time and keep credentials out of chat. If blocked, explain why.Confirm the workspace, and help me explore Metergraph's docs and capabilities.Suggest three metadata-first questions. Offer to install Metergraph's skillsfrom https://github.com/metergraph/skills (in Claude Desktop: Customize,Plugins, Add marketplace, metergraph/skills) so you can plan and run model-swapanalyses. Do not read retained content or run a replay unless I ask.Your agent will choose the access and credential steps for your deployment. Hosted cloud can offer account signup. The customer-local bundle uses its signed release and registry invitation. The open-source server needs no Metergraph account and uses an operator-set agent token. Enter credentials only in your client’s private settings. Codex may need a restart; a Claude Desktop connector must be enabled in the chat.
Check it in the conversation
Section titled “Check it in the conversation”Setup is complete when your agent has run metergraph status --json and
metergraph capabilities --json, or over MCP called
metergraph_get_workspace_context and metergraph_get_capabilities, and named
the workspace you intended. Then ask about its available capabilities or a
bounded metadata question. A missing key, wrong workspace, or unavailable
capability means setup still needs attention.
An ingest key sends traces from your application. A coding-agent key lets an agent read one workspace. Each coding-agent key has one of three roles, and each includes the one before it. Metadata reads content-free workspace telemetry and discovers capabilities. Debug adds retained trace content and report evidence. Replay adds bounded replay, which can call a configured external provider. You choose the role when you create the key. An owner’s new keys default to Debug, and a member can create Metadata keys only. If an owner changes the role under Connection access on the Keys page, Metergraph replaces the key. Update the saved credential in your agent.
If your agent needs the manual connection steps
| Deployment | MCP address after installation | Agent credential |
|---|---|---|
| Hosted cloud | https://app.metergraph.dev/v1/agent/mcp |
Coding-agent key from the hosted workspace’s Keys page |
| Signed customer-local bundle | http://127.0.0.1:8080/v1/agent/mcp on the bundle host |
Coding-agent key from that installation’s Keys page |
| Customer-owned AWS | Your installation’s actual origin plus /v1/agent/mcp |
Coding-agent key from that installation’s Keys page |
| Open-source self-hosted server | http://localhost:8787/v1/agent/mcp on the server host |
Operator-set MG_AGENT_TOKENS bearer token |
Use the address reachable from the client. localhost on a different
computer points to that computer, not the Metergraph host. Never reuse a
hosted key for a customer-operated installation.
Codex with hosted cloud
Create a coding-agent key in the intended hosted workspace. Load it
privately as METERGRAPH_AGENT_TOKEN in the environment that starts Codex.
Register the hosted server, then restart Codex:
codex mcp add metergraph --url "https://app.metergraph.dev/v1/agent/mcp" --bearer-token-env-var METERGRAPH_AGENT_TOKENThe command stores the variable name, not the token. See persistent credential setup if Codex does not see the token after restarting.
Claude Desktop with a hosted workspace
On an individual Claude account, open Customize → Connectors → Add custom
connector. Name it Metergraph and enter
https://app.metergraph.dev/v1/agent/mcp. If Request headers is
available, choose No sign-in and add a required header named
Authorization with value Bearer <your coding-agent key>. Enter the key
in Claude’s connector settings, never in chat. Enable Metergraph from
+ → Connectors in a new chat.
Request headers are in beta and available to a limited set of organizations. If the option is absent, this Claude Desktop path is unavailable for your account. Team and Enterprise connectors can share a fixed key across users; do not put one person’s workspace key in a shared connector. The remote connector runs in Anthropic’s cloud and cannot reach localhost.
Other deployments and clients
Section titled “Other deployments and clients”For the exact deployment differences, see Choosing a
deployment and Run it
yourself. The signed customer-local
bundle serves on port 8080
after installation and uses a coding-agent key from Keys. The open-source
server serves on port 8787,
needs no Metergraph account, and uses an operator-set MG_AGENT_TOKENS bearer
token for Agent Access. A customer-owned AWS
installation has its own identity and address, with no
public signup. Use the actual installation address and credentials; do not
reuse a hosted key or assume localhost refers to a different machine.
Claude Desktop’s remote connector runs in Anthropic’s cloud and cannot reach
a local or private-only address. Codex or Claude Code running on the customer
machine can connect to its local Agent Access endpoint. The stdio bridge needs
a separate metergraph-mcp installation on the client computer; a Docker
bundle does not install it there. Other local clients can use the instructions
shown after creating a coding-agent key in Keys when that deployment has
the Keys page.
ChatGPT uses a cloud MCP app. Metergraph setup for that client is not yet covered here, and a cloud app cannot reach a local or private-only address. Use Codex or Claude Code on the customer machine for a private deployment.
For tools and differences between server editions, see the MCP reference. To instrument a new application, start with Send your first trace. Your agent can do that without an MCP connection, using a separate ingest credential.
Keep Codex authenticated across sessions
codex mcp add saves an environment variable name. It does not save the
token or load it on a future launch.
On macOS or Linux, create a private file:
umask 077mkdir -p ~/.config/metergraphtouch ~/.config/metergraph/agent.envchmod 600 ~/.config/metergraph/agent.envOpen it in a local editor and add
export METERGRAPH_AGENT_TOKEN='YOUR_TOKEN', replacing the placeholder
there. Load that file in the shell or private launcher that starts Codex.
A desktop shortcut does not automatically source a terminal profile.
Restart the app or IDE after changing the token.
On Windows, save the token in an account-only private file, such as
%USERPROFILE%\.config\metergraph\agent.token, and load it from the
PowerShell profile or launcher used to start Codex:
$env:METERGRAPH_AGENT_TOKEN = (Get-Content -Raw "$env:USERPROFILE\.config\metergraph\agent.token").Trim()Check only whether the variable is set, without printing it. For terminal
Codex, run test -n "$METERGRAPH_AGENT_TOKEN" && echo 'Token is set' on
macOS or Linux, or [bool]$env:METERGRAPH_AGENT_TOKEN in PowerShell.
Let your agent write evaluations and start analyses
Section titled “Let your agent write evaluations and start analyses”Writing evaluations and starting analyses need three optional workflow permissions on top of the Debug or Replay role. Each one is off by default and unlocks its own tools. Only a workspace owner can grant them, and they work only while that owner remains an owner.
| Permission | Tools it adds | What the agent can do |
|---|---|---|
| Allow evaluation writes | 7 | Validate and save evaluation drafts, preview, apply and retire workload assignments, and bind reference cases. It makes no provider calls. |
| Allow evaluation previews | 1 | Test an evaluation draft against cases. A provider-backed preview also needs explicit egress consent and a bounded budget. |
| Allow analysis starts | 3 | Queue an analysis, classify recent traces, or start an experiment with metergraph_start_experiment. Running these can send captured content to your model provider and spend money. |
A Debug key without them lists 30 tools. With all three it lists 41. An agent that should write an evaluation and then run it needs all three: with only Allow analysis starts it can run analyses but cannot author or test the evaluations they use.
To grant them, open Keys, make sure the key’s Role is Debug or Replay under Connection access, tick the permissions under Optional workflow permissions, and click Change access and rotate key. Metergraph replaces the key, so update the saved credential in your agent. Workflow permissions are not available on an older key limited to specific environments.
Check analysis lifecycle
Section titled “Check analysis lifecycle”Ask your agent whether analyses have run. It calls
metergraph_list_analysis_runs (newest first, bounded, with
page.next_cursor for more) or metergraph_get_analysis_run with a known
run_id. Both need only the Metadata role and never start, cancel or rerun an
analysis. kind identifies classification checkpoints.
status describes the run’s lifecycle. report.available separately says
whether an imported report exists, and its analysis_id can be passed to
metergraph_get_report for the outcome. A completed run alone does not prove
a successful evaluation or an available report.