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. It can also call your own API, if you publish some of it — see Publish your API as tools.

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, send settings, 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.

Note

There is one more MCP surface in the app, and it is not this one. MCP is also a request protocol: a request whose protocol is MCP calls one tool on somebody else’s server, with the server as the request’s URL and an ordinary auth provider for the credential — and that server’s tool catalogue can be bound as a spec source the way an OpenAPI document is. That is Tinspec acting as an MCP client. This page is Tinspec acting as an MCP server.

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

Twenty-one tools. Read tools run immediately; the ones that send traffic, write files, or change the app’s state wait for your approval. 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 and variable keys), API providers.
set_environment	yes	Switch the active environment — the variable set every later send resolves against.
list_auth_providers · list_senders	—	Who you can send as: the auth providers and their senders, with a reason when one is not usable. Never a token or a secret name.
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, test results, and who it authenticated as.
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, plus the classified breaking changes and which of your own requests and chains they hit.
get_drift	—	Live responses that did not match the bound spec — an undeclared status, a missing required field, a type mismatch.
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: an OpenAPI-backed provider’s 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.

The one that is hard to do any other way:

“Does /admin/users really reject a viewer?”

list_senders names the identities the project can authenticate as, and the agent sends the same endpoint as each of them — one approval per send — then reports the matrix: a 200 where a 403 was expected, a 200 for another tenant’s user, a 500 instead of a refusal. It never sees a token; it only sees what each identity is allowed to do.

Publish your API as tools

The other direction: instead of teaching an agent to drive Tinspec, hand it your own API as tools — createOrder, listInvoices — so it never learns a URL, a header, or a token.

Turn it on per API provider, in that provider’s settings under Agent → Publish to your agent. Nothing is published until you do; an agent gaining the ability to call your API should be an act, not a setting that drifts on. Agent tools (command palette: Show Published Agent Tools) is the catalogue those choices produce.

• Scope is explicit. One tag, only the read-only verbs, or only what one auth rule’s sender can reach. Deprecated and x-internal endpoints are never published, and anything in scope that could not be published is listed with its reason rather than dropped.
• Each tool carries a resolved provider and sender. The identity is resolved from the provider’s own auth rules and is never told to the agent — it calls createOrder as tenant-admin and never sees the JWT. The approval card names the identity, because you are the one who needs to know.
• Argument examples come from real traffic. A body argument’s default is a body that actually produced a 2xx against that endpoint, secret-scrubbed — not a draft synthesized from types.
• A published call is an ordinary send. Same engine, same auth injection, same pre-run chain, same settings layers, same history and drift check — and the same approval card and audit row. Writes always prompt; reads follow the safe-methods setting below.

Details, including how tools are named and what is refused, are in MCP tools.

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, save_request, and set_environment always prompt — set_environment because switching the active environment changes what every later send resolves against, yours as well as the agent’s. Published tools follow the same rule by verb. 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 ****); the sent body is omitted entirely, since auth can be injected into one. Environment values are never returned — only variable names, which the agent uses as {{name}} placeholders. The auth tools name providers and identities and never a secret, not even a secret’s name. 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. Anything your request hooks printed goes there too, rather than into the agent’s result.

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 → AI → 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. A spec endpoint from an MCP tool catalogue can be sent too. WebSocket and streaming gRPC sessions, and LangGraph runs, stay in the app.
• An agent’s send is always buffered. SSE streaming belongs to the request editor, so an event-stream endpoint sent through a tool returns only when the stream closes.
• Switching the active environment is the only app state an agent can change. It cannot edit an environment’s values, an auth provider, or a sender, 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.
The agent cannot see a tool you just published	Tinspec sends no tools/list_changed; ask the agent to list its tools again.