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 API key as a plain bearer token. The scope on the key decides 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). A read-only management key is exactly the mgmt:read scope; write scopes are granted deliberately. See API key types for how scopes work.
SDK keys (scopes sdk:read/sdk:write) — including the key the CLI provisions into .traffical/.env — cannot read changes and will get a 403. You need a management key with mgmt:read (read-only) or a write scope.

​
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.