What this gives your AI

Most "AI + API client" integrations stop at autocompletion. This goes much further. When you wire @apicircle/mcp-server into Claude Desktop, Claude Code, ChatGPT, Cursor, Codex, Copilot, Continue, Cline, Zed, Windsurf — any MCP-compatible client — your assistant gains the ability to:

• Read your workspace. Browse requests, folders, environments, plans, and mock servers across multiple workspaces on the same machine.
• Author requests. Create, rename, move, and delete requests / folders / environments / assertions with prompt-driven, LLM-shaped JSON tools.
• Import specs. Drop in an OpenAPI / Swagger / Postman / Insomnia / HAR / cURL file and the assistant turns it into a typed collection.
• Generate code. Emit working clients in cURL, fetch, axios, Python requests, Go, and Rust for any request.
• Extract from your codebase. Scan an Express, FastAPI, NestJS, or Spring project and propose a request collection that mirrors the routes.
• Mock APIs. Boot a real local mock server from an OpenAPI spec — start, stop, and tear down — straight from the chat.
• Run + replay history. List history runs, replay them, purge old ones.

All without you leaving the conversation.

Install

# The common case — install globally and wire as a stdio MCP server
npm install -g @apicircle/mcp-server

# Or as a library, when you're embedding the host in your own product
npm install @apicircle/mcp-server

Quick start

# Multi-workspace mode (default) — exposes every workspace on this machine
apicircle-mcp

# Single-workspace mode — point at a folder with a workspace.synced.json
# (CI, a git-cloned workspace repo, etc.)
apicircle-mcp --workspace /path/to/checkout-repo

# Diagnostics — handled in-process, no MCP handshake involved
apicircle-mcp --version    # prints the package version
apicircle-mcp --help       # prints the usage block

The server speaks JSON-RPC on stdin/stdout (logs to stderr). Plug it into your AI client per the Connect your AI client guide, or copy/paste the snippet generated by the desktop app's MCP > Connection panel. It is the single setup-and-status surface: the workspace-mirror status and Refresh action stay above the "Set up your AI client" block.

Wiring it into an AI client

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "apicircle": {
      "command": "apicircle-mcp"
    }
  }
}

Same shape — a single command entry pointing at the apicircle-mcp binary. Use --workspace <path> to scope to one workspace.

How the server picks a workspace

apicircle-mcp auto-detects the directory passed via --workspace <dir> (or APICIRCLE_WORKSPACE):

| Contents of the directory | Mode | | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | registry.json present | Multi-workspace. Loads the registry, binds the active workspace, exposes the rest via workspace.list. | | workspace.synced.json only | Single-workspace. Legacy boot for CI / git-cloned repos. | | No flag at all | Falls back to the current working directory. |

In multi-workspace mode the assistant gets two extra surfaces:

• workspace.list — returns every workspace + per-workspace counts (requests, folders, environments, mocks, plans) + which is active. The response includes a hint field the AI can surface to the user when disambiguating between workspaces.
• workspace.read ambiguous envelope — when called with no workspaceId and more than one workspace exists, the response is a structured { kind: 'multiple-workspaces', activeWorkspaceId, workspaceCount, workspaces, hint } so the AI can clarify before drilling in.

{
  "kind": "multiple-workspaces",
  "activeWorkspaceId": "ws-a",
  "workspaceCount": 2,
  "workspaces": [
    { "id": "ws-a", "name": "Petstore", "isActive": true, "counts": { "requests": 12 } },
    { "id": "ws-b", "name": "Internal API", "isActive": false, "counts": { "requests": 47 } }
  ],
  "hint": "Found 2 workspaces. Re-call workspace.read with workspaceId set to the desired entry..."
}

Entity tools (request.read, environment.create, mock.start, etc.) all default to the active workspace — multi-workspace scoping is opt-in per call.

The tool catalog (74 tools)

The full list lives at docs/mcp-tools-reference.md. Highlights by category:

| Category | What the AI can do | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Workspaces | workspace.list, workspace.read, workspace.write (bulk + scoped by workspaceId) | | Entity CRUD | Requests, folders, environments, plans, assertions — full read / write surface | | Folder exchange | folder.export_json, folder.import_json — portable apicircle.folder/v1 envelope with embedded JSON Schema + GraphQL dependencies; credentials redacted by default | | Imports | import.curl, import.openapi, import.postman, import.insomnia, import.har | | Code generation | generate.code for cURL, fetch, axios, Python requests, Go, Rust | | Codebase analysis | codebase.extract_collection — Express, FastAPI, NestJS, Spring | | Prompt-driven authoring | LLM-shaped JSON entry points for request / folder / environment / assertion / plan / mock creation | | Mock servers | mock.create_from_openapi, mock.start, mock.stop, mock.delete, … | | History | history.list_runs, history.get_run, history.delete_run, history.purge_by_age |

Embed it in your own product

The host is plain TypeScript; the transport is plain stdio.

Single workspace, embedded

import {
  createMcpServer,
  FileBackedWorkspaceProvider,
  InProcessMockController,
} from '@apicircle/mcp-server';

const host = createMcpServer({
  workspace: new FileBackedWorkspaceProvider('/path/to/workspace'),
  mock: new InProcessMockController(),
});
await host.connect();

Multi workspace, embedded

import {
  createMcpServer,
  MultiWorkspaceProvider,
  InProcessMockController,
} from '@apicircle/mcp-server';

const workspaces = new MultiWorkspaceProvider('/path/to/workspaces-root');
const registry = await workspaces.init();
console.error(`Booting against ${registry.workspaces.length} workspace(s)`);

const host = createMcpServer({
  workspace: workspaces.activeProvider(),
  workspaces, // backs `workspace.list`
  mock: new InProcessMockController(),
});
await host.connect();

Provider interfaces

The host is decoupled from where state lives — swap providers to swap backends.

| Provider | Use when… | | ----------------------------- | ------------------------------------------------------------------------------------------- | | InMemoryWorkspaceProvider | Writing tests or programmatic embedding with ephemeral state. | | FileBackedWorkspaceProvider | CLI / headless use — advisory-locks the workspace file via proper-lockfile. | | MultiWorkspaceProvider | Registry-root-backed; implements the Workspaces interface that powers workspace.list. | | SingleWorkspaceAdapter | Wrap a single WorkspaceProvider so legacy single-dir hosts still answer workspace.list. | | InProcessMockController | Runs mocks directly via @apicircle/mock-server-core in-process. |

The Electron desktop app supplies its own IPC-backed providers so the renderer-side store stays the source of truth.

Use cases

• AI-pair-programming over your APIs. "Add an endpoint to delete a pet, generate a Go client, and write a smoke test." — done in one chat.
• Onboard a new dev by handing them an MCP-enabled assistant pre-wired to your team's workspace.
• Document drift detection. Have the AI scan your codebase, diff against the workspace, propose a PR.
• Spec-driven mocking. Drop an OpenAPI file in chat; ask the AI to spin up a mock; iterate on the frontend without touching the spec again.
• CI automation. Use the same MCP host as a headless executor for scripted, AI-authored regression suites.

Where it fits

@apicircle/shared              (types + MCP_TOOL_NAMES catalog)
└── @apicircle/core            (the engine that handles each tool call)
    └── @apicircle/mcp-server  ◀── you are here
        └── @apicircle/cli     (re-exports as `apicircle mcp`)

Learn more

• Full tool catalog: https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md
• Connect your AI client: https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md
• Platform architecture: https://github.com/apicircle/studio/blob/main/docs/architecture/platform.md

License

Released under the API Circle Studio License — a custom source-available license, not an OSI-approved open-source license. Free for personal, educational, and non-commercial use, plus a 30-day commercial evaluation period; ongoing commercial use requires a separate license. See LICENSE for the full terms, or contact [email protected] for commercial licensing.