Drive Impostor from AI (MCP server)

Impostor can act as an MCP server: a local AI agent (Claude Desktop, Claude Code, Cursor, GitHub Copilot — any MCP host) connects and gets a small set of tools to browse your workspace, inspect a request, and run one against its API — using the same engine and resolution the app uses.

This is the mirror image of the MCP client page (where Impostor connects to other MCP servers). Here, Impostor is the server.

Read-only and safe by default. The agent can list and run your saved requests, but secrets stay hidden, scripts never run, and it can’t reach outside the workspace. See Security.

How it works

The AI host launches impostor mcp on demand (a headless subcommand — no window, no extra memory in the app). It speaks MCP over stdio; there’s no network port or socket. The tools it exposes:

• list_workspace — the request tree + environments.
• get_request — one request’s definition (URL, headers, body, auth, variables), with {{templates}} shown as authored and secrets redacted.
• list_environments — environments and globals (secret values omitted).
• run_request — resolve a request (variables + folder inheritance) and send it, returning the response.
• get_history — recent run summaries.

By default the agent can only read and run. Enabling editing (see below) adds a few additive authoring tools: create_request, create_folder, create_environment, and set_environment_value.

Setup

The quickest way: click Connect MCP in the status bar (bottom-right). The popover gives you a ready-to-paste config with the real binary path filled in, a Copy button for both the JSON and the claude mcp add one-liner, a Pin this workspace toggle, the clear-on-exit setting, and hints for the MCP hosts it detects on your machine. Detected hosts with a config file we can write — Claude Desktop, Claude Code, Cursor — get a one-click Add to … button; it merges the entry in, leaving your other servers alone and saving a .impostor-bak backup first. The sections below are the same config, for reference.

You need the impostor binary path. On macOS it’s inside the app bundle: /Applications/Impostor.app/Contents/MacOS/impostor (not on PATH by default — use the full path, or symlink it: ln -s … /usr/local/bin/impostor). On Windows: C:\Program Files\Impostor\impostor.exe.

Keep the workspace open in Impostor and the config needs no workspace path — the server targets whatever you have open (see Active workspace).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{ "mcpServers": { "impostor": {
  "command": "/Applications/Impostor.app/Contents/MacOS/impostor",
  "args": ["mcp"]
}}}

Restart Claude Desktop, then ask: “List the requests in my Impostor workspace, then run ‘Login’ against the Local environment and show me the status.”

Servers added this way are listed under Settings → Developer, not Settings → Connectors (that page is for remote connectors and packaged extensions); their tools show up in the chat composer’s tools menu, grouped under impostor.

Claude Code

claude mcp add impostor --scope user -- /Applications/Impostor.app/Contents/MacOS/impostor mcp

Verify with claude mcp list; inside a session /mcp shows the tools.

Don’t drop --scope user. Without it claude mcp add defaults to local scope, which registers the server only for the directory you happened to run the command in — /mcp then shows nothing in every other project, even though ~/.claude.json clearly contains the entry (nested under projects.<dir>.mcpServers). If you’ve already hit this, re-run the command with --scope user; local-scope entries win for their own directory, so delete those too with claude mcp remove impostor from inside that directory.

This is also the config that the Claude desktop app’s Claude Code sessions read — they use ~/.claude.json, not claude_desktop_config.json. Adding the server for Claude Desktop’s chat does not make it appear in a Claude Code session, and vice versa. MCP servers are resolved when a session starts, so open a new session after adding.

Cursor / VS Code (Copilot)

Cursor — ~/.cursor/mcp.json:

{ "mcpServers": { "impostor": { "command": "impostor", "args": ["mcp"] } } }

VS Code (Copilot agent mode) — <project>/.vscode/mcp.json (note the servers key and explicit type):

{ "servers": { "impostor": { "type": "stdio", "command": "impostor", "args": ["mcp"] } } }

Active workspace

With no --workspace, the server drives whatever workspace you currently have open in Impostor — the app records a small pointer while it’s running, so the same static config follows you as you switch workspaces (reconnect the agent to pick up a switch).

By default the pointer is cleared when you quit Impostor, so the agent can only connect while the app is open. To target a fixed workspace instead (e.g. for a background agent), pin it explicitly:

{ "mcpServers": { "impostor": {
  "command": "impostor",
  "args": ["mcp", "--workspace", "/Users/me/Documents/my-workspace"]
}}}

Letting the AI edit

Editing is off by default. To let the agent create requests, folders, and environments, tick Let the AI edit the workspace in the Connect MCP popover (it adds --allow-write to the config) — or add the flag by hand: args: ["mcp", "--allow-write"].

The authoring tools are deliberately additive: there’s no delete, rename, or move, no full request overwrite, and secret variables can’t be set over MCP (a headless process can’t safely store them in your vault). Everything else stays read-only.

Security

The AI is treated as an untrusted caller and gets Impostor’s conservative defaults:

• Path-jailed to the workspace — request handles are workspace-relative; anything that escapes the root is rejected.
• Secrets redacted — secret-backed variables resolve to empty when a request is sent (a headless process can’t unlock your keychain), and run_request reports which ones in redactedVars so a resulting 401 is explained rather than mysterious. Secret values never appear in get_request / list_environments output.
• Scripts never run — pre/post-request scripts are skipped (with a note), and ƒx value scripts resolve empty.
• Read + run by default — authoring is opt-in (--allow-write), additive only, and never deletes.