MCP servers

StaticOwl ships with two Model Context Protocol servers, each at a different layer of the stack. They serve different purposes and have different blast radii.

Critical: do not expose the engine MCP to customer agents. It exposes raw query / mutate / fast_import over the entire graph engine, sees every tenant's data path, and bypasses Reviews, lifecycle hooks, audit chain, and schema validation. See Architecture: scoped agent tokens for the right shape for customer-facing agent access.

CMS MCP (@staticowl/mcp — gcms-mcp)

A stdio MCP server purpose-built for a single site. Lets agents do everything a human editor can: list and create content, run builds, inspect schema, navigate the graph (read-only).

Transport

Stdio. No HTTP transport in v1. Launch as a subprocess from the agent client.

Configuration

All via environment variables:

Launch

GCMS_ENDPOINT=https://api.graphiquity.com \
GCMS_API_KEY=gq_yourkey \
GCMS_GRAPH=mysite \
GCMS_SITE_ID=site:abc \
node packages/mcp/dist/index.js

Or via the bin: npx gcms-mcp (after npm install -g @staticowl/mcp).

Claude Desktop wiring

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "staticowl": {
      "command": "node",
      "args": ["/path/to/cms/packages/mcp/dist/index.js"],
      "env": {
        "GCMS_ENDPOINT": "https://api.graphiquity.com",
        "GCMS_API_KEY": "gq_xxxxxxxxx",
        "GCMS_GRAPH": "mysite",
        "GCMS_SITE_ID": "site:abc"
      }
    }
  }
}

Restart Claude Desktop; the StaticOwl tools appear in the model's tool list.

Tool inventory (current)

Tools registered by register*Tools in packages/mcp/src/tools/:

tools/content.ts

tools/schema.ts

tools/build.ts

tools/introspect.ts

What's NOT yet exposed (and why)

• No content_update — drafts only, no in-place edits via MCP yet. Add via tools/content.ts when the safety story is in place.
• No release/deploy tools — agents shouldn't trigger production deploys without human-in-loop. When added, they'll respect Reviews + auto-create an ai-kind Review for human approval.
• No write tools for templates, types, scripts — these are schema-level changes; gated behind admin UI for now.
• No agent-scoped tokens — current MCP runs with a graph-level engine API key. The right model is per-agent identities with scoped capabilities (content:draft:article, media:upload, etc.) — see Architecture: scoped agent tokens.

Auth model + threat surface

Today (graph-level engine key):

• The agent has every capability the engine API key has on the named graph
• A successful prompt injection in the agent → the agent could exfiltrate data, modify content, run arbitrary Cypher
• Use only with trusted users + trusted machines

Planned (agent-scoped tokens):

• Distinct Agent node in the graph + token namespace (gq_agent_…)
• Capability scopes (content:read, content:draft:article, media:upload)
• Resource filters (site allowlist, env allowlist, content-type allowlist)
• Auto-ai-Review on every write — non-bypassable
• Per-agent rate limit + TTL

Until that ships, treat MCP credentials like the engine API key they wrap.

Adding a new tool

packages/mcp/src/tools/yourdomain.ts:

import { GraphClient } from '@staticowl/core';
type ToolMap = Map<string, { description: string; inputSchema: any; handler: (args: any) => Promise<any> }>;

export function registerYourTools(tools: ToolMap, graph: GraphClient, siteId: string): void {
  tools.set('your_tool_name', {
    description: 'What this tool does for the agent.',
    inputSchema: {
      type: 'object',
      required: ['fooId'],
      properties: {
        fooId: { type: 'string', description: 'What this means' },
      },
    },
    handler: async (args: { fooId: string }) => {
      // Do the thing. Return JSON-serializable.
    },
  });
}

Then register in packages/mcp/src/index.ts alongside the others.

Engine MCP

Lives in the parent Graphiquity repo at mcp_server.js. Internal/admin only.

Transport

Dual:

• stdio — node mcp_server.js (developer / local-only)
• Streamable HTTP — mounted at /e/mcp on api.graphiquity.com. JWT auth via API Gateway.

Tool inventory (high level)

14+ tools spanning the engine surface:

• list_graphs, describe_graph, sample_data
• query, mutate, batch_query — raw Cypher
• explain — query plan
• run_algorithm — pageRank, connectedComponents, etc.
• create_graph, delete_graph — admin
• history, fast_import
• vector_search, create_vector_index, list_vector_indexes
• rebuild_derived — recompute derived indexes

Plus 2 resources (Cypher reference, per-graph schemas) and 3 prompts (explore_graph, find_connections, analyze_anomalies).

See the parent project's mcp_server.js for the full shape. Do not point customer-facing agents at this server.

Comparison

See also

• API reference — the HTTP routes that MCP tools delegate to
• Architecture — the data model the tools operate over
• Lifecycle hooks — what runs when MCP content_create writes