configure-zymtrace-mcp

Configure zymtrace MCP

Helps the user connect Claude Code (or Cursor / Claude Desktop / any MCP client) to their zymtrace backend's MCP server. Once connected, the user can analyze their CPU and GPU flamegraphs with natural-language queries — see analyze-zymtrace-workload for the analytical workflow.

The MCP server is part of the zymtrace backend itself — it lives at <gateway-host>/mcp. If the backend isn't installed and reachable yet, route to install-zymtrace-backend and expose-zymtrace-backend first.

Greet the user

👋 Let's connect Claude to your zymtrace MCP so you can analyze flamegraphs in natural language from this terminal. I'll need your zymtrace gateway URL and — if your install has service-token auth on — a token. Five minutes max.

Doc reference: https://docs.zymtrace.com/mcp/configure-mcp

Skip the greeting if the user has already volunteered the URL and token.

Sources of truth

• MCP configuration: https://docs.zymtrace.com/mcp/configure-mcp
• MCP token generation: https://docs.zymtrace.com/mcp/mcp-token
• MCP overview: https://docs.zymtrace.com/mcp

Pre-flight

Claude runs

claude --version
claude mcp list 2>&1 | head -20

If claude --version is older than v2.x → MCP support varies by version; recommend updating Claude Code. If zymtrace already appears in claude mcp list, the connection exists — jump straight to verification (Step 4).

Pre-resolve what you can

Variable	Resolve by
Backend gateway URL	Ask the user. Typically https://zymtrace.<their-domain> or the ALB / Ingress hostname. If installed in-cluster only, see "Port-forward fallback" below.
MCP endpoint	<gateway-url>/mcp — append /mcp to whatever they give you.
Auth required?	If the backend has auth.serviceToken.enabled: true (check with kubectl get cm -n <NS> -o yaml | grep -i serviceToken), the user needs a token. Otherwise skip.
Existing MCP servers	claude mcp list — to avoid name collision.

Things you must ask:

• The gateway URL (don't guess).
• Whether they want this connection at user scope (global) or project scope (just this repo).

Decision: auth or no auth?

Backend setting	What's needed
auth.serviceToken.enabled: false (default)	No token. Connection is open within the network that can reach the gateway.
auth.serviceToken.enabled: true	Token required. Generate one in the zymtrace UI: Settings → Service Tokens → New Token. Full doc: https://docs.zymtrace.com/mcp/mcp-token.

For production exposures behind ALB / NGINX / mTLS, service-token auth is recommended.

---

Standard flow

Step 1: Confirm reachability

Claude runs

curl -fsI <gateway-url>/health 2>&1 | head -3

Should return HTTP 200/204. If unreachable → the gateway isn't exposed externally; route to expose-zymtrace-backend or use the port-forward fallback below.

Step 2: Generate a token (only if service-token auth is enabled)

What you need to do in a terminal (user-driven)

The token is generated through the zymtrace UI, not by this skill:

1. Open the zymtrace UI: <gateway-url> (e.g. https://zymtrace.acme.com).
2. Settings → Service Tokens → New Token.
3. Scope it to mcp (or whatever scope the org uses).
4. Copy the token immediately — it's shown once. Store it in your password manager or $ZYMTRACE_MCP_TOKEN env var.

If your install doesn't have service-token auth on, skip this step.

Step 3: Confirm with the user before running

Print the exact command:

claude mcp add zymtrace --transport http <gateway-url>/mcp \
  --header "Authorization: Bearer $ZYMTRACE_MCP_TOKEN"   # only if auth is on

Wait for explicit confirmation. The $ZYMTRACE_MCP_TOKEN placeholder means the user exports the token in their shell first — never inline the literal token in the conversation or in files.

Step 4: Add the MCP server

What you need to do in a terminal

The user runs this (not the skill — the token is in their env):

# Auth-on case
export ZYMTRACE_MCP_TOKEN="<paste-token>"
claude mcp add zymtrace --transport http <gateway-url>/mcp \
  --header "Authorization: Bearer $ZYMTRACE_MCP_TOKEN"

# Auth-off case
claude mcp add zymtrace --transport http <gateway-url>/mcp

For project scope instead of user scope, add --scope project and the MCP config lands in .claude/settings.json for the current repo.

Step 5: Verify

Claude runs

claude mcp list | grep -i zymtrace

Should show the zymtrace server with Connected status. In a fresh Claude Code session, run /mcp and confirm zymtrace is listed.

Quick functional test:

Ask Claude (in a new session): "Using zymtrace MCP, list the top 5 hottest CPU functions from the last 1 hour."

If Claude returns data, the connection works. If it errors with unauthorized → token wrong, regenerate. If it errors with connection refused → gateway URL wrong or unreachable.

Step 6: Hand off

Direct the user to analyze-zymtrace-workload for the analytical workflow — workload classification (inference vs training), GPU↔CPU cross-view, pattern catalogues. That's where the connected MCP actually gets used.

Optional: pair with the GitHub MCP for code-level fixes

If the user also connects the GitHub MCP, Claude can pair the flamegraph analysis with the actual codebase — locating the hot function in their repo and proposing a specific edit (PR-ready), not just a generic recommendation.

What you need to do in a terminal

# Anthropic's first-party GitHub MCP, scoped to the relevant repo(s)
claude mcp add github --transport http https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_TOKEN"

Then in a session: "Analyze my GPU workload over the last hour, use the github MCP to find the code path in myorg/myrepo, and suggest a fix." Claude pulls the flamegraph from zymtrace, locates the hot frame in the repo via GitHub MCP, and proposes the edit. The two MCPs compose without any extra configuration on the skill side.

---

Port-forward fallback (for in-cluster-only gateways)

If the gateway has no external exposure (still ClusterIP), the user can MCP through a port-forward.

What you need to do in a terminal

kubectl port-forward -n <backend-NS> svc/<PREFIX>-gateway 8080:80
# Leave this running, then in another shell:
claude mcp add zymtrace --transport http http://localhost:8080/mcp

This is fine for dev / one-off investigations. For team-wide use, run expose-zymtrace-backend to give the gateway a real hostname.

---

Done

• claude mcp list shows zymtrace with Connected status.
• /mcp in a fresh Claude Code session lists zymtrace.
• A test query (e.g. "list top 5 hottest CPU functions in the last hour") returns data.

If all three check, hand off to analyze-zymtrace-workload.

Common pitfalls

• /mcp doesn't show zymtrace after claude mcp add → wrong shell scope. If you used --scope project, the server only appears when Claude Code runs in that repo. Add with no --scope flag (or --scope user) for global access.
• unauthorized on every query → token wrong, scoped wrong, or expired. Regenerate in Settings → Service Tokens.
• connection refused → gateway URL typo, missing /mcp suffix, or backend not exposed externally. Test with curl -I <gateway-url>/health first.
• Mixed Content in browser when testing UI on HTTP gateway → use HTTPS via expose-zymtrace-backend. MCP can stay on the same URL.
• Token committed to a values file or pasted into the session → revoke it in the UI immediately and re-issue. Tokens belong only in env vars or password managers.

Security constraints

• Never inline the MCP token in the conversation, values files, scripts, commits, or claude mcp add arguments. Always reference an env var ($ZYMTRACE_MCP_TOKEN) the user exports.
• Never generate, copy, or store the token on the user's behalf — the user pastes it once into their shell or password manager; the skill never sees it.
• Never run claude mcp add for them without explicit confirmation of the exact command + gateway URL.
• Never suggest disabling auth as a "fix" for an auth error. The fix is a valid token, not less security.
• Never declare the connection done without re-running /mcp or claude mcp list to verify.