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.First ask which deployment I use: hosted cloud, the signed customer-localbundle, customer-owned AWS, or the open-source self-hosted server. Guide accountcreation, invitation, sign-in, or installation as appropriate, then choosethe supported MCP setup for this client and runtime. Give me one action at atime and keep credentials out of chat. If blocked, explain why. After setup, callmetergraph_get_workspace_context and metergraph_get_capabilities, confirmthe workspace, and help me explore Metergraph's docs and capabilities. Suggestthree metadata-first questions. Offer to install Metergraph's skills fromhttps://github.com/metergraph/skills (in Claude Desktop: Customize, Plugins, Addmarketplace, metergraph/skills) so you can plan and run model-swap analyses.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 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. New keys start with Metadata. 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.
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.