MCP Integration

Purple8 ships a built-in MCP server (HTTP + SSE + Streamable HTTP). Any MCP-compatible AI agent — Claude Desktop, Cursor, GitHub Copilot, ChatGPT Desktop, or a custom agent loop — connects directly to the running Purple8 server and gets 85 typed tools across 13 namespaces.

Architecture

MCP Client (Claude Desktop / Cursor / ChatGPT Desktop / custom agent)
  │  MCP over Streamable HTTP (POST /mcp)  ← MCP 1.x clients
  │  MCP over HTTP + SSE (GET /mcp/sse)   ← legacy clients
  ▼
http://localhost:8000/mcp      ← built into the Purple8 server, no separate process
  │  internal call
  ▼
GraphEngine + JourneyEngine + RAG pipeline + Quantum engine (same process)

The MCP server runs as part of purple8_graph.secure_server — no separate process, no separate install. Start Purple8, both MCP endpoints are live.

---

Quick start

Step 1 — Start the server

export P8G_ADMIN_EMAIL=admin@example.com
export P8G_ADMIN_PASSWORD=changeme
export SECRET_KEY=your-secret-key
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...

python -m purple8_graph.secure_server
# Streamable HTTP: http://localhost:8000/mcp
# SSE (legacy):    http://localhost:8000/mcp/sse

Step 2 — Create an API key

TOKEN=$(curl -s -X POST http://localhost:8000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"changeme"}' | jq -r .access_token)

curl -X POST http://localhost:8000/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"claude-agent","role":"editor"}'
# Returns: { "key": "p8g_...", ... }  — store this, shown once

Step 3 — Connect via Claude CLI (recommended)

# Streamable HTTP — MCP 1.x (Claude Desktop 2026+, ChatGPT Desktop)
claude mcp add purple8 --transport http http://localhost:8000/mcp \
  --header "X-API-Key: p8g_your-key"

# SSE — legacy clients
claude mcp add purple8 --transport sse http://localhost:8000/mcp/sse \
  --header "X-API-Key: p8g_your-key"

Step 4 (alternative) — Connect Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "purple8-graph": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer p8g_your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop — all 85 Purple8 tools appear in the tool chooser.

Step 4 (alternative) — Connect Cursor

In Cursor settings → MCP → Add server:

{
  "purple8-graph": {
    "url": "http://localhost:8000/mcp",
    "headers": {
      "X-API-Key": "p8g_your-api-key-here"
    }
  }
}

---

All 85 tools across 13 namespaces

Namespace	Count	What agents can do
graph.*	23	Query, traverse, add/update/delete nodes and edges, PageRank, communities, centrality, link prediction, shortest path, CDC poll, auto-config, Moran's I
rag.*	6	Hybrid RAG query, graph-guided retrieval, profile and tune collection, rerank
data.*	5	Ingest text, ingest file (70+ formats via DocIntel), replace file, patch properties, list versions
journey.*	9	Define workflows, start/advance instances, SLA alerts, HITL gates, audit trail
schema.*	12	Define, get, update, delete, list node and edge types; validate graph against schema
memory.*	2	Agent decision history, semantic memory search
registry.*	5	Register external tools/MCP servers, list, test, remove
egress.*	4	Add/remove/status data sinks for CDC streaming
feedback.*	4	Open, record, resolve, summarise feedback loops
scheduler.*	4	Add/remove/status time-based and event-based triggers
quantum.*	8	QUBO/Ising optimisation (annealing, tabu), state encoding/measurement, VQE step, compare, profile
guardrails.*	1	LLM guardrails / content-safety evaluation
admin.*	2	SMTP status/configure (human_only — JWT required, not callable by agents)

---

RBAC per tool

RBAC is enforced per tool call via the role on the API key:

Role	Access
viewer	Read-only: graph.* reads, rag.*, memory.*, schema.* reads
editor	Viewer + writes: graph.* mutations, data.*, journey.start/advance, quantum.*, scheduler.*, egress.*, feedback.*
admin	Editor + admin: journey.define/resolve_hitl, schema.* mutations, registry.*, admin.smtp_status
super_admin	All tools

human_only tools — admin.smtp_configure and other destructive tools marked human_only=True are blocked for API-key (agent) callers. A human must authenticate via interactive JWT session to call them.

---

Authentication

All tool calls require X-API-Key: p8g_<key> or Authorization: Bearer <jwt> in the HTTP headers. API keys are created via POST /auth/api-keys or the LCNC dashboard at /lcnc/api-keys.

---

Example agent interactions

Build a knowledge graph from documents

User: "Ingest all PDF files in /data/contracts and build the knowledge graph"

Agent calls:
  data.ingest_file { "path": "/data/contracts/contract_001.pdf" }
  data.ingest_file { "path": "/data/contracts/contract_002.pdf" }
  ...
  graph.query { "label": "Entity", "limit": 10 }  ← verify ingestion

Answer a relational question

User: "What are the key risks across all projects owned by Alice?"

Agent calls:
  rag.hybrid_query {
    "question": "risks in projects owned by Alice",
    "fusion_alpha": 0.6,
    "max_hops": 2,
    "seed_k": 10
  }

Solve a scheduling optimisation problem

User: "Schedule 8 jobs across 3 machines to minimise total makespan"

Agent calls:
  quantum.scheduling {
    "n_jobs": 8, "n_machines": 3,
    "processing_times": [[2,3,1],[4,1,2],[1,2,4],[3,2,1],[2,1,3],[1,3,2],[4,2,1],[2,3,4]]
  }

Define and run a workflow

User: "Set up a loan approval workflow and start one for customer C-001"

Agent calls:
  journey.define { "name": "loan_approval", "stages": [...] }
  journey.start { "journey_name": "loan_approval", "entity_id": "C-001" }
  journey.status { "instance_id": "..." }

---

See Also

• RAG Pipeline — tuning retrieval for your corpus
• Journey Engine — workflows, SLA, and HITL
• Hybrid Search — vector + graph retrieval
• Encryption & KMS — what the agent can and cannot see