Purple8 MCP — Client Integration Patterns

Companion doc: MCP_GUIDE.md explains what the MCP server is, its tool namespaces, and RBAC. This doc is the practical, copy-paste reference for wiring every major AI client into a running Purple8 instance.

Purple8 exposes its entire backend (graph, vector, RAG, Journey Engine, ingestion, memory, quantum, evolution, sentinel, guardrails) as MCP tools — 125 MCP tools across 16 namespaces. Any MCP-compatible client can discover and call them. You do not write application code to give an agent this power; you point the client at Purple8 and the agent has the whole backend.

Self-Hosted Licensing Tiers: Developer (Self-Hosted Free) supports up to 50K nodes and 1 concurrent MCP agent. Enterprise / Custom (Self-Hosted) supports unlimited nodes and unlimited concurrent MCP agents.

---

1. Two transports — pick the right one

Purple8 speaks MCP over two transports. Every client below supports at least one of them.

Transport	How it runs	Best for	Endpoint / command
Remote (Streamable HTTP) — preferred	Client connects directly to a URL	Deployed/shared instances (AWS, Fly, K8s, SaaS), MCP 1.x clients	POST https://<host>/mcp with X-API-Key header
Remote (HTTP + SSE) — legacy	Client connects directly to a URL	Older remote-capable clients	GET https://<host>/mcp/sse with X-API-Key header
stdio bridge	Client launches a local process that proxies to the REST API	Local dev, clients without remote-MCP support	purple8-hyper-graph mcp-server --url <API_URL> --api-key <KEY>

Hosting checklist (TLS, P8G_PUBLIC_URL, proxy buffering, idle timeouts, SSE stickiness): see the published guide docs-site/docs/guides/mcp.md → Connecting to a hosted instance.

Rule of thumb:

• If your client can add a remote/URL MCP server → use the SSE endpoint. It is simpler, needs no local install, and works against a deployed instance.
• If your client only supports local/command MCP servers → use the stdio bridge. Install the SDK (pip install 'purple8-hyper-graph[mcp]') and let the client spawn it.

Both transports enforce the same tool-level RBAC and use the same API key (the X-API-Key generated inside your Purple8 instance — see §2). The MCP key is not the license JWT and not a user's login password.

---

2. Get an API key

Every connection needs an API key from the target Purple8 instance.

Via the LCNC admin console (easiest):

1. Open https://<host>/lcnc/api-keys (or http://localhost:8100/lcnc/api-keys locally).
2. + Create API Key → name it (e.g. claude-desktop), pick scopes, Create.
3. Copy the key once — it is shown a single time.

Via REST:

curl -X POST https://<host>/auth/api-keys \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"claude-desktop","permissions":["read","write"]}'

Keep the key secret. Scope it to the minimum permissions the agent needs — the MCP server additionally gates each tool by role (viewer / editor / admin).

---

3. Verify the endpoint before configuring a client

Confirm the instance is reachable and the key works:

# Health (no auth)
curl -s https://<host>/health

# MCP initialize handshake — prints 200 when the key works
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://<host>/mcp -H "X-API-Key: <KEY>" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'   # 200 OK, 401 bad key, 404 no [mcp] extra

A 401 means the key is wrong or missing; a 404 on /mcp means the MCP transport is not mounted (install the [mcp] extra on the server in v0.72.0).

Hosted instances (AWS / Fly / Kubernetes / SaaS): <host> is your instance's public HTTPS name, and the key must be issued by that instance — a key from your local install will return 401. If /health works but /mcp times out or hangs behind a load balancer, see §6 Hosting checklist.

---

4. Client configurations

Each section is self-contained. Replace <host>, <KEY>, and paths as noted.

4.1 Claude Desktop

Claude Desktop launches local MCP servers, so use the stdio bridge.

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "purple8": {
      "command": "purple8-hyper-graph",
      "args": [
        "mcp-server",
        "--url", "http://localhost:8100",
        "--api-key", "YOUR_API_KEY"
      ]
    }
  }
}

If purple8-hyper-graph is not on the global PATH, use the absolute path to the binary inside your venv (e.g. /path/to/.venv/bin/purple8-hyper-graph). Restart Claude Desktop; the Purple8 tools appear under the 🔌 (plug) menu.

Remote instances: Recent Claude Desktop builds also support Custom Connectors (remote MCP over HTTP). If yours does, add a connector pointing at https://<host>/mcp with an X-API-Key header instead of the stdio block above — no local install required.

4.2 Claude Code (CLI)

Claude Code supports both transports via claude mcp add.

Remote (recommended for deployed instances):

claude mcp add --transport http purple8 \
  https://<host>/mcp \
  --header "X-API-Key: YOUR_API_KEY"

stdio (local dev):

claude mcp add purple8 -- \
  purple8-hyper-graph mcp-server --url http://localhost:8100 --api-key YOUR_API_KEY

List/verify:

claude mcp list

Scope with --scope user (all projects) or --scope project (checked into .mcp.json for the repo). Then inside a session: "List the Purple8 MCP tools and profile the default collection."

4.3 Claude Web (claude.ai)

Claude Web connects to remote MCP servers only — there is no local process. Use the SSE endpoint.

1. Settings → Connectors → Add custom connector (availability depends on your Claude plan; Team/Enterprise and Pro have rolled this out).
2. Name: Purple8
3. URL: https://<host>/mcp
4. Header: X-API-Key: YOUR_API_KEY

Claude Web requires a publicly reachable HTTPS URL. A localhost instance will not work — deploy first (see DEVELOPER_INTEGRATION.md) or expose it through a tunnel (cloudflared, ngrok) for testing. Always terminate TLS in front of Purple8.

4.4 VS Code (native MCP + Copilot Agent Mode)

VS Code has native MCP support. Add a workspace file .vscode/mcp.json:

Remote (SSE):

{
  "servers": {
    "purple8": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": { "X-API-Key": "${input:p8gKey}" }
    }
  },
  "inputs": [
    { "id": "p8gKey", "type": "promptString", "description": "Purple8 API key", "password": true }
  ]
}

stdio (local dev):

{
  "servers": {
    "purple8": {
      "type": "stdio",
      "command": "purple8-hyper-graph",
      "args": ["mcp-server", "--url", "http://localhost:8100", "--api-key", "${input:p8gKey}"]
    }
  },
  "inputs": [
    { "id": "p8gKey", "type": "promptString", "description": "Purple8 API key", "password": true }
  ]
}

Open Copilot Chat → Agent mode; the Purple8 tools appear in the tools picker. The ${input:...} prompt keeps the key out of source control.

4.5 OpenAI Codex (CLI & IDE)

Codex reads MCP servers from ~/.codex/config.toml.

stdio (local bridge):

[mcp_servers.purple8]
command = "purple8-hyper-graph"
args = ["mcp-server", "--url", "http://localhost:8100", "--api-key", "YOUR_API_KEY"]

Remote (SSE) — if your Codex version supports URL servers:

[mcp_servers.purple8]
url = "https://<host>/mcp"
headers = { "X-API-Key" = "YOUR_API_KEY" }

Restart Codex. Confirm with codex mcp list (CLI) or the IDE tools panel. If your Codex build only supports stdio, keep the bridge form.

4.6 Cursor

Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

Remote (SSE):

{
  "mcpServers": {
    "purple8": {
      "url": "https://<host>/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

stdio (local dev):

{
  "mcpServers": {
    "purple8": {
      "command": "purple8-hyper-graph",
      "args": ["mcp-server", "--url", "http://localhost:8100", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Settings → MCP shows a green dot and the tool count when connected.

4.7 Windsurf (Codeium)

Windsurf reads ~/.codeium/windsurf/mcp_config.json. Same schema as Cursor:

{
  "mcpServers": {
    "purple8": {
      "command": "purple8-hyper-graph",
      "args": ["mcp-server", "--url", "http://localhost:8100", "--api-key", "YOUR_API_KEY"]
    }
  }
}

For a deployed instance, use the serverUrl / remote form if your Windsurf version supports it, pointing at https://<host>/mcp with the X-API-Key header.

4.8 Cline / Roo Code (VS Code extensions)

Open the extension's MCP Servers → Configure panel (writes cline_mcp_settings.json):

{
  "mcpServers": {
    "purple8": {
      "command": "purple8-hyper-graph",
      "args": ["mcp-server", "--url", "http://localhost:8100", "--api-key", "YOUR_API_KEY"],
      "disabled": false
    }
  }
}

For remote, set "url": "https://<host>/mcp" and "headers": { "X-API-Key": "YOUR_API_KEY" } instead of command/args.

4.9 Continue (continue.dev)

Add to ~/.continue/config.yaml:

mcpServers:
  - name: purple8
    command: purple8-hyper-graph
    args:
      - mcp-server
      - --url
      - http://localhost:8100
      - --api-key
      - YOUR_API_KEY

4.10 Any other MCP client (generic)

• Remote-capable client: point it at https://<host>/mcp (Streamable HTTP) with header X-API-Key: YOUR_API_KEY. Legacy SSE-only clients use https://<host>/mcp/sse; their messages are POSTed to /mcp/messages/ automatically by the SSE session.
• stdio-only client: have it launch purple8-hyper-graph mcp-server --url <API_URL> --api-key <KEY> and speak JSON-RPC 2.0 over stdin/stdout.

Custom Python agent (stdio):

import subprocess, json
proc = subprocess.Popen(
    ["purple8-hyper-graph", "mcp-server",
     "--url", "http://localhost:8100", "--api-key", "YOUR_API_KEY"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True,
)
# Then exchange JSON-RPC 2.0 frames on proc.stdin / proc.stdout
# (initialize → tools/list → tools/call ...).

---

5. Config cheat-sheet

Client	File	Transport(s)	Key field
Claude Desktop	claude_desktop_config.json	stdio (remote via Connectors)	mcpServers.purple8.command
Claude Code	claude mcp add	HTTP + stdio	--transport http / --
Claude Web	Settings → Connectors	HTTP only	custom connector URL
VS Code	.vscode/mcp.json	HTTP + stdio	servers.purple8.type
Codex	~/.codex/config.toml	stdio (HTTP if supported)	[mcp_servers.purple8]
Cursor	~/.cursor/mcp.json	HTTP + stdio	mcpServers.purple8
Windsurf	~/.codeium/windsurf/mcp_config.json	stdio (HTTP if supported)	mcpServers.purple8
Cline / Roo	cline_mcp_settings.json	stdio + HTTP	mcpServers.purple8
Continue	~/.continue/config.yaml	stdio	mcpServers[]

For every remote row, the URL is https://<host>/mcp whether <host> is localhost:8100, your own AWS/Fly/Kubernetes deployment, or a Purple8 SaaS instance. For the stdio bridge, --url is the same host without /mcp.

---

6. Hosting checklist (self-hosted cloud)

Skip this if you use Purple8 SaaS — it is operated for you.

Item	Why
[mcp] extra installed in the image	Otherwise /mcp and /mcp/sse are not mounted (mcp_*_transport_skipped in logs)
TLS terminated at ALB / ingress / Fly	API keys travel in headers
P8G_PUBLIC_URL=https://<host>	Each MCP session calls tools back through this URL; without it the server falls back to the request base_url, which is often an internal http:// address behind a proxy
Proxy buffering off for /mcp* (proxy_buffering off; on nginx)	Both transports stream responses
LB idle timeout ≥ 300 s (AWS ALB default is 60 s)	Long tools (rag.tune_collection, quantum.*) hold the stream open
Sticky sessions only for /mcp/sse	SSE's GET /mcp/sse and POST /mcp/messages/ must hit the same replica; /mcp is stateless per request
WAF allows /mcp*	Some managed rule sets block text/event-stream or JSON-RPC bodies

---

7. First things to ask the agent

Once connected, confirm the toolbelt is live:

• "List the available Purple8 MCP tools by namespace."
• "Profile the default collection and recommend RAG settings." → rag.profile_collection
• "Ingest this text into the graph, then answer a question from it." → data.ingest_text + rag.hybrid_query
• "Define a 3-stage approval workflow with an SLA and a human gate." → journey.define

You can also browse the full catalogue, RBAC badges, and a live connection snippet in the LCNC MCP Console at https://<host>/lcnc/mcp.

---

8. Troubleshooting

Symptom	Cause	Fix
401 Unauthorized on connect	Wrong/expired API key	Regenerate at /lcnc/api-keys; check the header name is exactly X-API-Key
404 on /mcp	MCP transport not mounted	Install [mcp] extra on the server; confirm build is v0.72.0
Tools list is empty	Key lacks any role	Give the key at least viewer; check tool RBAC in the MCP Console
Client shows "server exited" (stdio)	purple8-hyper-graph not on PATH	Use the absolute venv path in command
Claude Web can't connect	localhost / no HTTPS	Deploy or tunnel; Web needs a public HTTPS URL
A specific tool call returns 403	Tool requires a higher role	Elevate the key's permissions or the caller's role
Connection drops after idle	Proxy/idle timeout on the stream	Raise the LB idle timeout (Fly/ALB) to ≥ 300 s
/health OK but /mcp hangs or tool calls time out	Proxy buffering, or P8G_PUBLIC_URL unset behind a proxy	See §6
401 with a key that works locally	Key belongs to a different instance	Create a key on the hosted instance's /lcnc/api-keys

---

9. Security notes

• One key per client. Name them (claude-desktop, vscode-agent) so you can revoke individually from /lcnc/api-keys.
• Least privilege. Scope keys to read for query-only agents; only grant write/admin where the agent must mutate the graph or resolve HITL gates.
• TLS always. Terminate HTTPS in front of Purple8 (Fly handles this; on AWS use an ALB/API Gateway). Never send X-API-Key over plain HTTP off-box.
• The MCP key ≠ the license JWT. Rotating one does not affect the other.
• Audit. Every MCP tool call is attributed (actor = mcp-server/<key>) and written to the immutable graph audit trail; review via /admin/audit or the MCP Console Activity view.

---

See also

• MCP_GUIDE.md — tool namespaces, RBAC, walkthroughs
• DEVELOPER_INTEGRATION.md — deploy on Fly/AWS then connect apps + agents
• CLOUD_DEPLOYMENT_GUIDE.md — platform-by-platform infra guide