Skip to main content
Traffical exposes an MCP server. Connect an AI agent and it can read your changes — state, evidence, decision records — and, where governance permits, act: draft changes, propose or execute lifecycle transitions, and record assessments. The server is least-privilege by scope, not read-only: a token’s scopes bound what it can do, the autonomy resolver narrows that at runtime, and a write mode that defaults to off gates every lifecycle transition. Approvals stay with humans — there is no approve tool; when an action needs a checkpoint, the agent raises a proposal and links you to the transition console in the dashboard.
The Changes surface is enabled per organization — if you don’t see Changes in the dashboard sidebar, it isn’t enabled for your organization yet.

​
Connect

Traffical provides your organization’s MCP endpoint during onboarding — reach out if you don’t have it yet.

​
Claude Code

That’s it — no key to paste. Claude Code discovers the authorization server via standard OAuth discovery and opens a browser sign-in with your Traffical account. Run /mcp inside Claude Code to authenticate or check connection status.

​
Other MCP clients

Any MCP client that supports streamable HTTP with OAuth discovery works zero-config. Point it at your organization’s MCP endpoint; the first 401 response carries a WWW-Authenticate header pointing at the server’s OAuth discovery document (/.well-known/oauth-protected-resource on the endpoint’s origin), which names the authorization server, and the client runs the standard OAuth flow from there. Two transport details for client authors:
  • The server speaks plain JSON-RPC 2.0 over POST /mcp — no sessions, no SSE streams (GET /mcp returns 405).
  • OAuth tokens are audience-bound (RFC 8707): the token must be minted for the MCP resource. Clients that follow the discovery flow get this right automatically.

​
API key (headless agents, CI)

For agents that can’t run a browser flow, use a management key (traffical_mk_...) or an admin key (traffical_ak_...) as a plain bearer token. The permissions on the key decide what it can do:
Create one on your organization’s API Keys page in the dashboard (in the sidebar when viewing your organization, or from the account menu). See API key types for the full reference.
The key must carry the mcp:invoke permission, and it is not included in the default management-key preset — grant it explicitly when you create the key. Without it every request returns 403 Required permission: mcp:invoke.
SDK keys — publishable (traffical_pk_...) and server-side (traffical_sk_...), including the keys the CLI provisions into .traffical/.env — cannot reach the control plane at all and will get a 403. SDK keys serve config and events; they are a different surface.

​
Scopes

Three write scopes sit on top of the read scopes. tools/list is scope-filtered, so a token only sees the tools its scopes permit. You never mint these fine-grained scopes directly — they come from the coarse scope on the key, or from your role over OAuth. mgmt:read grants every :read scope; mgmt:operate (the Lifecycle Operate Key preset) grants all three write scopes; admin (Full Access) grants everything. A plain mgmt:write key grants none of the write scopes, and over OAuth only admins and owners carry them — members and viewers connect read-only. See API key scopes. Scope is the durable ceiling; the autonomy resolver narrows it again at runtime, per action.

​
Tools

​
Read tools

preview_transition and get_autonomy are advisory — they show what would happen and why, but change nothing. Omit kind on preview_transition to preview the natural next step.

​
Write tools

These appear in tools/list only when the token carries the scope.

​
How writes are governed

Even with a write scope, no transition executes unconditionally. The autonomy resolver evaluates each request and returns execute or propose, weighing the caller’s scope, the change’s computed risk class, the action’s direction (risk-decreasing actions like revert are always auto-eligible), guardrail breaches, and whether measured evidence meets the plan’s minimums — agent assessments never satisfy that gate. Approvals and autonomy covers the full model. Three connection-level guarantees:
  • No approve tool. Approval happens only in the dashboard transition console, which makes it structurally human. A proposed result carries a consoleUrl deep link for review.
  • No certified protocol, no traffic. A change whose plan matches no certified measurement protocol cannot begin serving traffic until a human approves a measurement plan.
  • Everything is audited. Every MCP-originated write lands on the decision log as “Agent, on behalf of <human>, via MCP.”

​
Write mode

Lifecycle transitions are off by default. A global write mode gates every transition — request_transition, and create_change’s optional start — with per-organization enablement on top; the effective mode is the lower of the two: Write mode governs the actions that move traffic. The advisory writes — drafting changes, assessments, annotations, evidence refreshes, approval requests — serve no traffic and are bounded by their scopes instead, so they work in any mode. Read-only tokens carry no write scope and cannot be replayed against write tools; every tool enforces the same per-project access checks as the management API.

​
Companion agent skill

For Claude-family agents, the open-source traffical-changes skill (github.com/traffical/skills) teaches the agent to use these tools well — and to respect the boundary that humans own approvals:
It’s the operate-time sibling of the build-time Agent Skill, which covers parameters, SDK wiring, and config-as-code.

​
Next steps

Changes

What a change is and how its measured lifecycle works.

Approvals and autonomy

The full governance model behind execute vs propose.

Agent Skill

The build-time skill: setup, parametrizing code, SDK wiring, events.

API overview

API key scopes and how authentication works.