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 supports the stable 2025-11-25 revision and retains 2025-03-26 compatibility:

POST http://localhost:8000/mcp
X-API-Key: <your-api-key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

It implements the stable lifecycle (initialize, then notifications/initialized) plus ping, tools/list, and tools/call. It holds no server-side MCP session store, so any request can be served by any instance. Subsequent requests carry the negotiated revision in MCP-Protocol-Version; a missing header follows the stable specification's explicit 2025-03-26 compatibility assumption. There is no separate process or port. Each call passes the control plane's existing session-or-key authentication and tenant scope. The same license snapshot and authorization policy filter both tools/list and tools/call.

Gostly has no server-to-client MCP message stream, so an authenticated GET /mcp returns 405 with Allow: POST. Browser callers must exactly match MCP_ALLOWED_ORIGINS; normal server clients omit Origin. Raw POST bodies are capped by MCP_MAX_REQUEST_BODY_BYTES (1 MiB by default) before UTF-8 decoding or JSON parsing.

Connecting a client

For an inspection-only client, generate a user API key in Settings; the full key is shown only once. User keys are deliberately read-only because they do not carry a user role or per-key scopes. A mutation-capable key client must use the system-managed service key. Signed-in dashboard sessions can read at viewer and mutate at member or above. If a request sends both a valid session cookie and a key, the session takes precedence.

Point the client at the endpoint with the chosen key in X-API-Key. For Claude Desktop, add the server to claude_desktop_config.json and restart:

{
  "mcpServers": {
    "gostly": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "<user-or-service-key>"
      }
    }
  }
}

Swap localhost:8000 for the host your control plane is reachable on if the client runs elsewhere. The discovered catalog will reflect that credential's access level and the deployment's enabled features.

The tools

The backend keeps one closed definition, handler, authorization, and public-projection registry. The catalog below mirrors that registry, while runtime discovery remains the authority for what a particular client may call. Read tools inspect state; mutate tools change control-plane or boot-local agent state.

A typical agent loop

A client should begin with tools/list and compose its workflow from the returned subset. A mutation-capable environment workflow will typically:

Discovery and execution use the same authorization decision. Tool results also pass a tool-specific public projection before they are returned. A read-only tools/call looks like this:

curl -X POST http://localhost:8000/mcp \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_drift",
      "arguments": { "unacknowledged_only": true }
    }
  }'

MCP controls the same environment; it does not introduce a separate request-matching 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. Calls use an existing login session, system service key, or user-generated key and operate within the resolved tenant. Session role or key type determines read versus mutate access.
• Closed tool surface. At startup, definitions, handlers, access policies, and public projectors must name the same tools. An incomplete registration fails closed, and discovery and execution share one policy decision.
• Projected public results. Tool responses pass explicit allowlists, scrubbing, and size bounds. Unsafe or oversized results fail instead of returning the handler's raw value.
• Mutations are explicit. The current surface can change services, mocks, modes, adapters, fault settings, evaluations, and isolated episode state. reset_episode can wipe an explicit boot-local episode; scenario-pack tools only preflight candidates and never admit them to the agent.
• Self-hosted boundary. The MCP endpoint runs in your Docker stack. Data returned to an MCP client follows that client's own deployment and trust boundary, so configure remote clients accordingly.