Model Context Protocol (MCP)
MCP — the Model Context Protocol — is the open standard for letting AI agents talk to tools and data sources. Restura plays both sides.
As an MCP client
Section titled “As an MCP client”Point Restura at any MCP server and explore it like any other request target.
streamable-httptransport — the modern wire shape.http-ssetransport — the legacy (2024-11-05) shape, shown as HTTP + SSE in the transport selector; desktop only the web build supports onlystreamable-http. The transport is fixed while connected: disconnect to change it.stdiotransport desktop only — start a local MCP server (npx,uvx,docker run, a binary) and talk to it over stdin/stdout. See Local servers over stdio.{{variables}}in the URL — autocompleted and highlighted (unresolved names are flagged). Resolved from globals, the environment, the collection and its folders at connect time. A variable stored as a keychain or external secret refuses the connection.- List tools — see the server’s exposed tool catalogue with schemas.
- Invoke a tool — fill in the arguments form built from the tool’s input schema (it validates arguments before sending), send, and inspect the result.
enumarguments are selects, booleans are switches, numbers show and check theirminimum/maximum, and schemadefaults prefill an unsaved form. Raw JSON edits the whole arguments object as JSON instead; a tool whose schema lists no argument fields always uses it. A tool call returns one result; on desktop, progress and log messages for an in-flight call show in the Events tab. - Result view — Pretty / Raw / Tree, a JSONPath query, find, copy, and download for every tool result or error payload.
- Tool titles and hints — discovery shows each tool’s display
titleand itsannotationsas badges (read-only, destructive, idempotent, open-world). Hints are declared by the server and are not verified; invoking a tool markeddestructiveHint: true(and not read-only) asks for confirmation first. - Tool errors vs protocol errors — a tool that fails reports
isError: trueinside a successful response; the result panel and call log show it as a red TOOL ERROR, distinct from a PROTOCOL ERROR (JSON-RPC or transport failure).restura runalso fails the item for a tool error and words the message differently from a JSON-RPC error. - Structured output — when a tool declares an
outputSchema, the result panel validatesstructuredContentagainst it and flags mismatches (or a missingstructuredContent); you can viewstructuredContenton its own. - Code — the Code button generates a cURL (raw JSON-RPC) or TypeScript SDK (
@modelcontextprotocol/client) snippet. Headers are used as typed:{{variables}}stay unresolved and Auth-tab credentials are not included. - Connection headers — bulk edit (one
key: valueper line,//to disable a row) and an optional description per row; values resolve{{variables}}. - Scripts — pre-request and test scripts in the app can use
rs.sendRequest, cookies and the vault, and test scripts can users.judge, as gRPC scripts do. The CLI doesn’t wire these. - List prompts / list resources — for servers that expose them. Lists follow
nextCursorpagination automatically. Read a resource to see its contents, or Get a prompt (filling in its arguments) to see the messages it returns; each call appears in the Log tab. - Resource templates — when the server advertises
resources, a Templates tab listsresources/templates/list. Selecting one opens a form with a field per RFC 6570 URI-template variable (levels 1–3, values percent-encoded), a live preview of the expanded URI, and Read. - Argument completion — when the server advertises
completions, prompt arguments and template parameters suggest values viacompletion/complete(debounced, previously entered arguments sent as context). - Log level and ping — a Ping action shows the round-trip time; when the server advertises
logging, a picker sendslogging/setLevel. Both calls appear in the Log tab. These work on web, self-hosted, and desktop.
Authentication
Section titled “Authentication”Open Auth under the URL bar to authenticate the connection:
- None — no credential (folder / collection auth is still inherited, as for HTTP requests).
- Bearer — sent as
Authorization: Bearer <token>(the MCP authorization spec’s header). - API Key — sent as a request header you name (e.g.
X-API-Key). MCP credentials never go in the query string, so there is no query-param option. - OAuth 2.1 desktop — the MCP authorization flow. See OAuth 2.1 sign-in below.
Values resolve {{variables}} and apply on every request of the session, on every harness:
- Desktop — the credential field can be stored in the OS keychain (or point at an external secret manager). Restura keeps only an opaque handle in the request; the desktop app resolves it at connect time, so the token never enters the UI, saved collections, or exports. A handle that no longer resolves fails the connect instead of opening an unauthenticated session.
- Web not persisted — the browser has no OS keychain, so an MCP request’s own credentials (its auth token, credential-named headers such as
Authorization/X-Auth, and credentials in the server URL —user:pass@and?api_key=-style query values) are never written to browser storage: they live only for the current session and must be re-entered after a reload. Auth configured on a folder or collection is stored with the collection as usual. Keychain handles are desktop-only — a request that uses one fails to connect in the browser with a clear error. - CLI —
restura runapplies the same auth (handles are unavailable; supply the value with--env).
Secret variables (keychain-backed {{variables}}) are not resolved inside MCP auth fields or headers yet — use a keychain-stored credential in the Auth field instead.
A redacted collection export (the default, without “include secrets”) blanks MCP header and auth credentials (handles are kept as references); an export with secrets included keeps them. Imported Basic or OAuth 2.0 access-token auth is still sent as an Authorization header; schemes that sign the request (Digest, OAuth 1.0, AWS SigV4, NTLM, WSSE) aren’t supported for MCP — a request’s own one fails the connect, and an inherited one is skipped.
OAuth 2.1 sign-in
Section titled “OAuth 2.1 sign-in”Pick OAuth 2.1 for servers that use the MCP authorization spec. Click Connect. If the server answers 401, Restura:
- Discovers the server’s protected-resource metadata (RFC 9728, from the
WWW-Authenticateheader or the well-known URL), then the authorization server’s metadata (RFC 8414). It checks that the advertisedissuermatches. - Registers itself with the authorization server through Dynamic Client Registration (RFC 7591), unless you enter a Client ID. A pre-registered confidential client can also take a Client secret; store it in the keychain. A secret requires the Authorization server issuer it is registered with, and Restura refuses to send it to any other server. A public client with a Client ID is pinned to the first authorization server it signs in with, until you sign out.
- Opens your system browser to sign in, using PKCE (S256) and a
resourceindicator (RFC 8707). The browser redirects back to a one-time listener onhttp://127.0.0.1:<random port>. Restura accepts only the callback carrying the exactstateit sent, then closes the listener. Sign-in times out after 5 minutes. If your authorization server requires a fixed redirect URI, enter one such ashttp://127.0.0.1:8765/callback(localhostisn’t accepted) under Redirect URI. - Exchanges the code for tokens and connects.
The desktop app stores tokens in the OS-keychain-encrypted secret store and refreshes them before they expire. The UI, saved collections, exports, the console, and history never see them. The Auth panel only shows whether you’re signed in, with a Sign out button (also listed in Settings → Secrets). Your next connect reuses the stored sign-in without opening the browser. If a refresh fails mid-session, the connection asks you to click Connect to sign in again; Restura never opens a browser window on its own.
OAuth requires an https MCP server URL; plain http works only for a loopback development server. A remote server’s authorization endpoints can’t point at localhost or private addresses. Every discovery, registration, and token request goes through the desktop SSRF guard. Each request must use https; plain http is allowed only for a loopback development server, and only while localhost is allowed in Settings → Security. Cloud-metadata and private addresses are blocked, every DNS lookup is checked and pinned, redirects are re-checked on each hop and never replay a POST, and responses are size-capped. Design notes: ADR 0031.
The browser build and the CLI don’t run this sign-in. The web Auth panel hides the option. In the browser, or in CI with restura run, use an access token as Bearer auth.
Local servers over stdio
Section titled “Local servers over stdio”desktop only Most MCP servers are local programs. Choose the stdio transport, enter the command (a name on your PATH, such as npx, or an absolute path), then open Launch settings:
- Arguments — one per line, passed to the program exactly as written. Blank lines are ignored. No shell is involved, so quotes,
$VARS,*and|are not interpreted. - Working directory — an absolute path. It defaults to your home directory.
- Environment — the extra variables the server needs, such as an API key. Values resolve
{{variables}}. A variable can also come from the desktop secret store; the app resolves it when the server starts.
Connect starts the process, runs the MCP handshake, and lists the server’s tools, prompts and resources, just like the HTTP transports. The server’s stderr appears under the connection bar (the newest 64 KB; output beyond 512 KB per session is dropped), and a failed start shows the end of stderr in the error.
Arguments, the command and the working directory can’t contain control characters, invisible formatting characters (such as right-to-left overrides or zero-width spaces) or line breaks. Environment values may contain tabs and line breaks (for example a PEM block) but no other such characters. Relative command paths such as ./server aren’t accepted. On Windows, network (\\server\share) paths aren’t accepted for the command or the working directory.
Consent: you approve every new command line
Section titled “Consent: you approve every new command line”Starting a program is a different kind of risk from sending a request: the program runs with your user account and can read and change your files. Before Restura starts a command line it has not run before, the desktop app finds the exact program file and shows a system dialog with:
- the full path of the program (and the name you typed, if different);
- every argument;
- the working directory;
- the environment variables.
You then choose:
- Cancel (the default) — nothing starts.
- Allow once — start it this time and ask again next time.
- Always allow — remember this exact command line on this computer.
Any change to the program, an argument, the working directory or an environment variable (name or value) is a new command line and asks again. That includes a changed secret behind a secret-store variable.
How environment values appear in the dialog:
- Values are shown in full, except values whose name looks like a credential (for example
API_KEYorGITHUB_TOKEN). Those are hidden but still count as part of the command line. A value that looks like a file path is always shown. - Variables that change what runs or where it connects are always shown in full and must be plain values, not secret-store references. Examples:
PATH,NODE_OPTIONS,LD_*/DYLD_*,NPM_CONFIG_*,PYTHON*,GIT_*, proxy and CA-bundle variables. - Secret-store variables show the label saved with the secret. Only variables with credential-like names can come from the secret store.
- Invisible or control characters are shown as
\u{...}escapes, so the dialog can’t be made to read differently from what runs.
Very long arguments or values are cut in the dialog with a “more characters not shown” note. In that case only Allow once is offered.
Approvals are stored by the desktop app and protected with your operating system’s keychain. A collection, an imported file, or anything else in the request can’t carry or pre-grant an approval: an imported stdio request still asks the first time you connect. If the keychain isn’t available (for example on Linux without a keyring), Restura can’t remember approvals and asks every time. Forget approvals under Launch settings clears every remembered approval.
Approving a command line doesn’t vouch for the code it runs. The program file, the scripts it loads, or a downloaded package can change later. For example, npx -y some-package runs whatever that package publishes at the time.
What the process gets
Section titled “What the process gets”- A minimal environment, not the app’s. The server receives
PATH,HOME(or the Windows equivalents such asUSERPROFILEandSystemRoot),SHELL,TERM,USER, the temp directory and your locale settings, plus the variables you set. Tokens and credentials in Restura’s own environment are not passed on. - No shell. The program is started directly. On Windows,
.cmd/.batlaunchers such asnpx.cmdrun throughcmd.exe, and the dialog says so. Arguments for them can’t contain",%or!; to pass those, start the underlying.exe(for examplenode.exewith the script path) instead. - Your secrets, if you give them. Secret-store variables are passed to the server as plain values. A server that prints them sends them to its stderr, which Restura shows.
- It stops when you do. Disconnecting, closing the tab or window, or quitting Restura stops the process. If it ignores the request to exit, it is killed after one second. On Windows the whole process tree is ended. At most 8 stdio servers run at once.
Environment values are exported like request headers. When secrets are excluded from an export, and always when a collection is saved to files, values with credential-like names are written without their value, and only references to the secret store are kept.
stdio is not available in the web app, the self-hosted server, or the CLI. A saved stdio request opened there explains that it needs the desktop app, and restura run fails the item without starting anything. The design and its residual risks are recorded in ADR 0030.
Importing from Claude Desktop, Cursor or VS Code
Section titled “Importing from Claude Desktop, Cursor or VS Code”Click Import next to Tools in an MCP request to bring in servers you already configured elsewhere. Restura understands:
- Claude Desktop
claude_desktop_config.jsonand Cursormcp.json(themcpServersmap) - VS Code
mcp.json(theserversmap andinputs) and themcp.serverssetting insettings.json
Local entries (command, args, env, cwd) become stdio requests; remote entries (url, type of http, streamable-http or sse, headers) become Streamable HTTP or HTTP + SSE requests. You always get a preview with a checkbox per server before anything is created, and the servers are saved together in an Imported MCP servers collection.
- Desktop. Detect installed apps looks in the standard locations for Claude Desktop, Cursor (
~/.cursor/mcp.json) and VS Code. Choose file… opens a native file picker, which is the way to import a project’s.cursor/mcp.jsonor.vscode/mcp.json. The desktop app reads the file itself; nothing outside those locations and the file you pick is read. - Web. Paste the JSON or upload a file (up to 1 MB). Only remote (HTTP) servers can be imported; local servers are listed as desktop-only.
- Secrets. On desktop, environment variables with credential-like names (for example
GITHUB_TOKENorAPI_KEY) are stored in the secret store, never shown in the preview and never saved in your collection. Other variables stay visible so you see exactly what a server will start with, including variables that change how a program runs (such asNPM_CONFIG_*settings), which can’t be hidden and are shown in full in the approval prompt. Credentials written into arguments (--token abc) or URLs (?api_key=) are masked in the preview only and are imported exactly as written, so review them before you import. - Approval is still required. Importing a local server never approves it. The first time you connect, Restura shows the same approval prompt as for a server you typed in yourself.
- VS Code placeholders.
${input:id}and${env:NAME}are turned into Restura{{id}}and{{NAME}}variables (define them in an environment) and Restura warns you. It does not read variables from your computer’s environment. A working directory like${workspaceFolder}is dropped, because the directory must be an absolute path. - Files that can’t be imported. Files over 1 MB, files that are not valid JSON, and entries of an unknown type are reported in the preview and skipped.
Desktop protocol compatibility
Section titled “Desktop protocol compatibility”The desktop app connects with the current MCP v2 client. Its automatic version negotiation supports both modern v2 servers and legacy MCP servers during the connection handshake, so saved MCP requests do not need a protocol-version setting. stdio servers are the exception: they connect with the standard initialize handshake, because the client’s automatic negotiation would start a second, hidden copy of the server to probe it.
Legacy negotiation is handled inside the v2 client. Restura does not construct a second SDK client or retry authentication, TLS, DNS/SSRF policy, network, or timeout failures, so those errors remain visible rather than being masked by another connection attempt.
On desktop, after connecting, Restura uses the v2 client’s typed operations for every standard request supported by the negotiated protocol era: ping, completion, legacy logging level, tools, prompts, resources (including subscriptions), and v2 server discovery. That preserves the client’s protocol-era validation, pagination, caching, and modern HTTP behavior instead of treating a production MCP server as an untyped JSON-RPC endpoint. Non-standard server extensions remain explicit requests so their server-provided JSON-RPC errors can still be inspected.
This compatibility path is desktop-only. The web and self-hosted clients retain their existing stateless Worker proxy behavior, and http-sse remains desktop-only.
Web and self-hosted session lifecycle
Section titled “Web and self-hosted session lifecycle”The web and self-hosted clients send each JSON-RPC message through the /api/mcp proxy. They follow the Streamable HTTP lifecycle themselves:
- Handshake.
initializeoffers the newest protocol version that theinitializehandshake supports. This is the same version the desktop SDK offers in its handshake.clientInforeports the real Restura version. The negotiated version is stored and shown next to the connection status. Restura sendsnotifications/initializedbefore any other request. - Version header. Every request after
initializecarriesMCP-Protocol-Versionwith the negotiated value.initializeitself never carries it. - Disconnect. Disconnecting sends
DELETEwithMcp-Session-Idthrough/api/mcp/terminate, so the server can free the session. Servers that answer405(termination not allowed) or404(session already gone) are treated as success. A reconnect also ends the previous session first. - Session expiry. A
404on a request that carried a session id means the session expired. Restura re-runs the handshake once, which opens a new session, and retries the request once. If concurrent requests all hit404, they share a single re-initialize. - Server messages in a reply. A server can send other messages before its reply on the same SSE stream, such as progress, logging or server-to-client requests. These are returned to the client with the reply (
serverMessages) instead of being dropped. The web client doesn’t answer server-to-client requests or multi-roundinput_requiredresults. It advertises no client capabilities, so tools that need elicitation, sampling or roots are not supported on the web — use the desktop app (see Elicitation, sampling and roots below).
desktop only Web limitations:
- There is no standalone
GETlistening stream, so server messages sent outside a request aren’t delivered. - There is no SSE resumption with
Last-Event-ID. If a reply stream drops mid-call, the call fails.
Use the desktop app for long-lived subscriptions.
Modern server coverage
Section titled “Modern server coverage”Restura’s v2 test server exercises modern discovery alongside tools, prompts, resources, cache hints, schema-declared request headers, multi-round input_required responses, and change subscriptions. The MCP workspace presents the core catalogue and request operations, plus server notifications and resource subscriptions on desktop.
Elicitation, sampling and roots desktop only
Section titled “Elicitation, sampling and roots ”Servers sometimes need something from the client mid-call. The desktop app advertises the elicitation (form mode), sampling and roots (with listChanged) client capabilities and answers those requests, both as 2025-era server→client requests and as 2026-07-28 multi-round input_required tool, prompt and resource results. In the second case the tool call simply completes once you answer.
- Elicitation opens a form built from the server’s
requestedSchema(the same field editor as tool arguments). Accept sends the content only after it passes the schema check, which runs in the form and again in the main process. Decline and Cancel send the matching spec action. Closing the dialog counts as Cancel. URL-mode elicitation is not advertised. - Sampling is never answered automatically. The dialog shows the system prompt, every message, the model preferences and
maxTokens. You write the assistant response, or click Draft with … to fill it in from the provider configured for the AI assistant. The draft is sent with secret redaction on, and nothing reaches the server until you click Approve & send. Reject (or closing the dialog) returns a “user rejected” error to the server. - Roots: the Roots panel under the connection bar holds a per-connection list of
file://URIs, saved with the connection. The server receives this list fromroots/list. Saving an edit sendsnotifications/roots/list_changedto a connected server.
A prompt nobody answers expires after 5 minutes. A server may have at most 8 prompts waiting per connection. Prompts are withdrawn when the server cancels the request or the connection closes. Answers are accepted only from the window that opened the connection. Every prompt names the connection and server host and carries a fixed warning never to enter passwords or API keys. Fields whose name or format suggests a secret are masked and flagged. Pressing Enter never accepts a form, and focus starts on Decline or Reject. Roots must be local file:// paths: no remote host and no credentials. Server requests larger than 100 KB are refused. On 2025-era servers the tool call that triggered the prompt keeps its own request timeout (60 seconds by default). If you take longer to answer, that call fails even though the prompt is still open.
The web build cannot receive server→client requests because its Worker proxy is request/response only, so these flows exist only in the desktop app.
Server notifications and resource subscriptions
Section titled “Server notifications and resource subscriptions”desktop only On desktop, the catalog panel has an Events tab that shows what the server pushes during the live session (newest first, last 200 events):
- Progress for in-flight tool calls, as a progress bar per call. Restura asks for progress on every
tools/call, so servers that support it sendnotifications/progress. - Log messages (
notifications/message) with their level and logger. - List changes —
tools,resources, orpromptslist_changed. Restura re-runs discovery so the catalogue stays current. - Resource updates (
notifications/resources/updated) for resources you subscribed to. - Connection errors and closure. If the server drops the connection, the status changes to Error and shows the reason, such as the last transport error, instead of staying “connected”.
When the server advertises resources.subscribe, each resource in the Resources tab has a Subscribe / Unsubscribe toggle. Restura picks the method that matches the negotiated protocol version:
| Server era | Subscribe | list_changed delivery |
|---|---|---|
| 2025-era (legacy) | resources/subscribe / resources/unsubscribe | Pushed unprompted on the session stream |
| 2026-07-28 (modern) | One subscriptions/listen stream per resource (closed on unsubscribe; at most 32 per connection) | A subscriptions/listen stream that Restura opens automatically after connecting |
Restura opens and closes subscriptions/listen streams itself, so you can’t send a raw subscriptions/listen request. If the server ends a subscription stream, the Events tab records it and the toggle switches back off.
The web and self-hosted builds don’t have these features. Their Worker proxy handles only one response per request, so the server has no channel to push events to the browser.
The same URL validation, pre-flight DNS check, header policy, and Electron IPC validation apply before the SDK is allowed to connect. MCP connections are not pinned to the address that was checked; see ADR 0006 for the residual risk.
Cancelling a call
Section titled “Cancelling a call”While a tool call or prompt fetch is in flight, the Invoke form shows a Cancel button. Cancelling follows the MCP Cancellation utility: the client sends notifications/cancelled with the cancelled request’s id and a reason, and any response that arrives afterwards is ignored. The result panel and call log show the call as cancelled, not as an error.
- Desktop: the renderer calls the validated, owner-scoped
mcp:cancelIPC channel, which aborts the SDK request signal; the SDK emitsnotifications/cancelled. - Web and self-hosted: the browser aborts its
/api/mcpfetch and posts a separatenotifications/cancellednotification (with the session id when the server issued one) through the same proxy.
Conformance report
Section titled “Conformance report”The Conformance action on an MCP connection answers “does my server work across client eras?”. It connects to the server separately in the legacy era (initialize, protocol versions up to 2025-06-18) and the modern era (server/discover, 2026-07-28), runs the same scripted sequence in each, and renders a report you can export as Markdown or JSON.
Per era it checks:
- the negotiated protocol version and
serverInfo(name and version), and thatcapabilitiesis a well-formed object; - that an unknown method is rejected with JSON-RPC
-32601; tools/list,resources/listandprompts/list(only the ones the server advertised): result shape,nextCursorpagination (empty or repeated cursors, runaway paging), duplicate names or URIs, and tool descriptors that fail normalization (missinginputSchema, malformedoutputSchemaorannotations);- optional sample tool calls:
structuredContentvalidated against the tool’soutputSchema, a missingstructuredContentwhen anoutputSchemais declared, andstructuredContentwithout a text content block.
It then diffs the two eras (protocol version, serverInfo, capabilities, and the tool, resource and prompt listings including changed descriptors). A server that only speaks one era is reported as such, not as a violation of the other; failing to connect in the legacy era is an error.
Sample calls are off by default. Read-only tools calls only tools the server claims are read-only (readOnlyHint: true; the claim is not verified), with minimal arguments synthesized from the inputSchema. Read-only + chosen tools additionally calls the non-read-only tools you tick. Tools marked destructiveHint: true (including ones that also claim readOnlyHint) and tools with duplicate names are never called in any mode, and annotations are server-declared hints, so only tick tools you trust. Call payloads are never stored in the report. Descriptor bodies (schemas, descriptions) are reduced to a name plus content hashes, server-provided strings are length-bounded, stripped of control characters and escaped in Markdown, your header values are scrubbed from every string, lists and findings are capped (1000 / 500), and the report’s target has credentials and query string removed. The whole run has a hard deadline and every connect is bounded by the configured timeout.
| Where | Eras covered |
|---|---|
| Desktop app | Both (legacy and a pinned 2026-07-28 connection) |
| Web / self-hosted app | Legacy only: the /api/mcp proxy is a stateless JSON-RPC relay with no era negotiation |
CLI (restura mcp conformance <url>) | Both, over streamable-http or http-sse (the modern era needs streamable-http) |
The desktop and CLI runs use the official SDK client’s list calls, which validate and aggregate pages themselves, so a server that violates the wire schema surfaces as a failed list call rather than as individual descriptor findings.
Testing MCP servers in collections and CI
Section titled “Testing MCP servers in collections and CI”A saved MCP request is one operation: the method and params you build in the invoke form (for example tools/call with {"name":"echo","arguments":{"text":"hi"}}). Saved requests run in the collection runner (desktop and web) and in restura run with pre-request and test scripts, so you can regression-test an MCP server the same way you test an HTTP API.
- One session per server per run. The runner connects and initializes once per server (same URL, transport and headers), reuses that session for every MCP item, and closes it when the run ends.
{{variables}}resolve in the URL, headers, method and params. A pre-request script can set them, for example to choose the tool arguments for the call. In params, variables are substituted as text before the JSON is parsed, the same as in HTTP bodies. A value containing quotes or other JSON syntax changes the params structure, so only use trusted values there.- The response body is the JSON-RPC reply, without the transport id, so a test can tell the outcomes apart:
const body = rs.response.json();// Success: { jsonrpc: '2.0', result: { content: [...], isError?: true } }// JSON-RPC error: { jsonrpc: '2.0', error: { code, message, data? } }// Test script of a `tools/call` request for the echo tool:rs.test('echo tool replies', () => { rs.expect(body.result.isError).to.not.equal(true); rs.expect(body.result.content[0].text).to.equal('echo:hi');});// Test script of a request whose method the server doesn't implement:rs.test('unknown method is rejected', () => { rs.expect(body.error.code).to.equal(-32601); // Method not found});- Pass/fail. With no assertions, an item passes only on a plain result. A tool result with
isError: trueor a JSON-RPC error fails it, and the reason is shown. With assertions, the assertions decide, so you can write negative tests that expect an error. A connection, HTTP or timeout failure always fails the item, whatever the test script asserts. - No saved method: the item fails with an actionable error. Nothing is sent.
- Auth: both runners apply the request’s own auth, or the folder/collection auth it inherits, as headers: Bearer, Basic, API key (header only; MCP has no query channel) and OAuth2 access tokens. The desktop OAuth 2.1 authorization-code sign-in uses the interactive desktop connection and is not available in collection runs; in CI pass a token through a variable or Bearer auth. Keychain handles (
SecretRef) are desktop-only and rejected by collection runs, so use inline or variable values there. You can still set a header directly, for exampleAuthorization: Bearer {{token}}. - Transports:
http-sseruns on desktop and in the CLI. The web runner supportsstreamable-httponly.
The local echo stack’s generated collection (npm run echo:local, see echo-local/README.md) includes runnable MCP examples for a tool call, a tool isError result, a JSON-RPC error and a resource read. Each example has its own test script.
Using MCP elsewhere in Restura
Section titled “Using MCP elsewhere in Restura”- Collection runner and CLI — saved MCP requests run with scripts and assertions; see Testing MCP servers in collections and CI.
- AI Lab agents — in the desktop app, an agent can use a saved MCP connection as a tool source, optionally limited to an allowlist of tool names. Tool discovery and each tool call open a fresh session over
streamable-httporhttp-sse; stdio connections are not supported as agent tool sources yet. In CI,restura agent evalaccepts MCP tool sources only when the runtime manifest declares them read-only with a tool allowlist. See AI Lab — Tools, grounding, and approval and CLI — Agent eval. - Workflows — MCP tasks are not supported yet; a workflow that contains one is rejected. See Workflows.
As an MCP server
Section titled “As an MCP server”Restura can also be an MCP server. In the desktop app, turn on Settings → MCP Server and connect Claude Code, Codex or Claude Desktop with Restura --mcp-server. The agent can then read, build and send your collections, folders, requests and environments, with:
- Consent per collection (hidden / read / read & edit / full) and per environment, with a separate opt-in for sending with each environment.
- Approval in Restura for edits (unless you auto-approve them), and always for deletes and sends.
- Redaction of credentials in everything the agent reads. Secrets are typed by you, never passed through the agent.
The server runs inside the app on 127.0.0.1 and uses the v2 server package, which serves modern and legacy clients. Sends go through the same collection runner as the Runner dialog.
See the MCP server mode guide for setup.
Related
Section titled “Related”- AI assistant — Restura’s built-in chat with OpenAI / Anthropic / OpenRouter, which can use request context and tools.
- MCP server mode — set up Restura as an MCP server in your agent.