The MCP Server

What it is

The MCP server is a thin, tenant-scoped control surface served by the control-plane API on the same port as the rest of the REST API. It speaks the MCP 2024-11-05 protocol over a single JSON-RPC endpoint:

POST http://localhost:8000/mcp
X-API-Key: <your-api-key>
Content-Type: application/json

It implements the three JSON-RPC methods an MCP client expects — initialize, tools/list, and tools/call — and advertises a tools capability. There is no separate process and no separate port: every call is authenticated with the same X-API-Key header as the rest of the control plane and is scoped to the calling tenant.

Connecting a client

Generate an API key in the dashboard under Settings (the full key is shown only once, at generation time). Then point your MCP client at the server URL with that key in the X-API-Key header. For Claude Desktop, add the server to claude_desktop_config.json and restart:

{
  "mcpServers": {
    "gostly": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "<your-api-key-from-settings>"
      }
    }
  }
}

The dashboard's MCP Server page generates this block pre-filled with your server URL and a key prefix, with a one-click copy. Swap localhost:8000 for the host your control plane is reachable on if the agent runs elsewhere.

The tools

The server exposes sixtools. Four are read-only (discovery and inspection); two mutate state (switch mode, author a mock). Every tool is scoped to the calling tenant — an agent can only ever see and touch its own deployment's data.

A typical agent loop

The tool roster is designed around one workflow: find the gaps, then close them. An agent asked to make a test suite pass against mocks will typically:

Every tools/callruns the same control-plane logic the dashboard uses. The read tools query the tenant's Postgres-backed library directly; get_unmatched and set_mode forward to the proxy agent; create_mock writes the library entry and then signals the agent to reload. A raw tools/call looks like this:

curl -X POST http://localhost:8000/mcp \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "set_mode",
      "arguments": { "mode": "MOCK" }
    }
  }'

The agent never bypasses the deterministic match cascade. When it switches to MOCK mode, requests are still served exact-match first, then session-verbatim replay, statechart/resource transitions, and smart swap before any AI generation — and AI generation runs on a background worker, never in the request hot path. See How It Works for the full cascade.

Boundaries and safety

The MCP server inherits the product's structural guarantees — it is a control surface, not a back door:

• Authenticated and tenant-scoped.Every call requires a valid API key and operates only on the calling tenant's data. Gostly is single-tenant per deployment, so in practice the agent sees exactly one environment — its own.
• Bounded tool surface. The agent can list, inspect, record, switch mode, and author mocks. It cannot delete the library, export data, manage users, or touch billing — those surfaces are not exposed as tools.
• Redaction still applies. Credential headers are stripped before anything is written to disk, and mocks the agent reads through list_mocks reflect the same scrub boundary as the rest of the library. The MCP server adds no new data path that escapes it.
• Self-hosted. The server runs inside your own Docker stack. No request, mock body, or coverage report leaves the box because of MCP.