Agent access (MCP)

With Agent access on, the running desktop app is an MCP server on 127.0.0.1, behind a bearer token. Your own agent connects to it and can explore the project you have open, send requests, run chains, and read history.

Whatever project the app has open is what the agent sees. Every request it sends goes through the same engine as a click on Send — the same auth injection, the same {{variable}} resolution, the same cookie jar, gateways, and history.

This is the opposite direction from AI assist. There, Tinspec calls a model with your API key. Here, your agent calls Tinspec: the tokens are yours, and no inference goes through us.

Setup

1. Turn it on. Settings → AI → Agent access (MCP). This is its own consent switch, separate from AI assist — you can have either without the other. The app picks a port, mints a token, and shows both.
2. Connect your agent. Copy the ready-made snippet next to the token; it already contains the port and the token.
3. Keep a project open. With none open, tools answer no project is open in Tinspec.

Claude Code

claude mcp add --transport http tinspec http://127.0.0.1:<port>/mcp \
  --header "Authorization: Bearer <token>"

Claude Desktop, Cursor, and other mcpServers clients

{
  "mcpServers": {
    "tinspec": {
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Regenerating the token disconnects every agent; each one needs the new value. The port is stable per machine once assigned.

What an agent can do

Seventeen tools. Read tools run immediately; the ones that send traffic or write files wait for your approval in the app. The full catalogue with arguments is in MCP tools.

Tools	Asks first	What for
get_active_project · list_environments · list_providers	—	Orientation: the open project, environments (names only), API providers.
list_endpoints · describe_endpoint	—	Search spec-derived endpoints; read parameters, body schema, an example body, responses, and which auth provider applies.
list_requests · get_request	—	Saved, hand-authored requests in the project.
send_request	yes	Send one request — a spec endpoint with overrides, or an ad-hoc request object. Returns status, headers, body, timing, and test results.
list_chains · run_chain	yes	List chains; run one with inputs. Only run_chain prompts.
plan_prerequisites · save_chain	yes	Plan a setup chain for an endpoint from the spec; save it. Only save_chain prompts.
get_history · get_run	—	Previous runs, timings, statuses, and test results.
get_spec_changes	—	Endpoints added, removed, or modified since you last reviewed the spec.
import_curl	—	Turn a curl command into a request object (not saved).
save_request	yes	Persist a request into the project as YAML.

Agents can also read four resources: the provider’s OpenAPI document (tinspec://spec/<provider>), a collection file (tinspec://collection/<file>), the most recent response (tinspec://response/last), and the agent skill (tinspec://skill).

A typical exchange

“Log in as the staging admin and show me which /orders calls return 500.”

The agent reads the project and environment, finds the endpoints, runs the login chain, sends the requests one by one — each landing as an approval card in the app — and reads the responses and history back to you. Every run is in History, tagged mcp.

Approvals & safety

You approve every send. A card appears in the app — Claude Code wants to send DELETE /users/42 — with Allow, Deny, and Allow all from this agent this session. ⌘⇧↵ allows, ⌘⇧⎋ denies. A denied call returns denied by user to the agent.

send_request prompts for every non-GET/HEAD/OPTIONS method, and for safe methods too unless you opt into letting those through. run_chain, save_chain, and save_request always prompt. Session allow-alls reset when the server stops or the client disconnects.

Secrets never cross. Auth tokens are injected by the engine and masked in what the agent sees (Bearer ****). Environment values are never returned — only variable names, which the agent uses as {{name}} placeholders. The keychain is not reachable through any tool.

Local only. The server binds to 127.0.0.1, never a network interface, and refuses requests without the token. It is off by default and stops when you turn it off or quit.

Audited. Agent sends and chain runs land in History with the agent’s name alongside your own runs, and a live Agent activity panel shows every tool call, its timing, its outcome, and each approval decision.

Response bodies do go to the agent. That is the point — but it means the data reaches whichever model your agent uses. Bodies are truncated to the response-size limit, and the agent is told when that happens. Turn agent access on per machine, knowingly.

The agent skill

Tools alone do not tell an agent how to work: to describe before sending, to warn you before an approval card appears, never to paste tokens into headers, to use {{name}} rather than asking for values, to add tests from the spec’s documented responses, never to hand-write chain YAML.

Tinspec ships that playbook as an agent skill (a SKILL.md):

• Every connected agent can read it as the resource tinspec://skill — the server’s own instructions point there first.
• For Claude Code, Settings → Agent access → Install for Claude Code writes it to ~/.claude/skills/tinspec/SKILL.md; new sessions pick it up.
• For other agents, Copy SKILL.md and drop it into that agent’s skills or rules folder.

Limits

• The desktop app must be running with a project open; there is no headless mode.
• HTTP, GraphQL, and unary gRPC only. WebSocket and streaming gRPC sessions, and LangGraph runs, stay in the app.
• Agents cannot edit environments or auth providers, and cloud features are not exposed.
• Transport is streamable HTTP on loopback. Clients that only speak stdio are not supported.

Troubleshooting

Symptom	Cause
Connection refused	The app is not running, or agent access is off. The Settings status line reads running · port when it is up.
401	Wrong or regenerated token. Copy the snippet again.
no project is open in Tinspec	Open a project in the app.
The agent says it timed out	An approval card waited 60 seconds without an answer. Look at the app.