Graph-OS MCP Server Examples

The graph-os MCP server is the unified entrypoint for interacting with the Intelligence Graph Engine. Intent mode starts with exactly six intent tools and five control tools. Granular capabilities such as those below are not part of that initial surface: discover them through list_catalog, load only the required capability with load_tools, use it, and release it with unload_tools.

The following are selected examples of dynamically loaded granular capabilities, not an exhaustive startup-tool inventory.

1. mcp_graph-os_graph_ingest

Handles smart ingestion for codebases, documents, directories, conversations, agent skills, and mcp servers.

Example 1: Ingesting an Agent Toolkit Ingest mcp_config.json files and skill directories.

{
  "action": "agent_toolkit",
  "target_path": "[\"/path/to/universal-skills\", \"/path/to/mcp_config.json\"]"
}

Example 2: Ingesting a Codebase Trigger full AST parsing and semantic chunking of a repository.

{
  "action": "ingest",
  "target_path": "${WORKSPACE_ROOT}/my-repo",
  "max_depth": 3
}

Example 3: Checking Job Status

{
  "action": "job_status",
  "job_id": "job-3d73bbc4"
}

Running jobs include their attempt, resource lane, heartbeat, and lease-expiry timestamps. These fields distinguish live progress from a worker whose renewable lease is waiting to expire after a crash.

2. mcp_graph-os_graph_search

Search the Knowledge Graph using multiple strategies.

Example 1: Hybrid Search (Semantic + Keyword)

{
  "mode": "hybrid",
  "query": "authentication flow architecture",
  "top_k": 5
}

Example 2: Concept ID Lookup Fetch the exact topological subgraph for a known concept.

{
  "mode": "concept",
  "query": "CONCEPT:AU-OS.identity.auth-flow",
  "top_k": 1
}

Example 3: Tiered Memory Search Search episodic or procedural memory for past agent actions.

{
  "mode": "memory",
  "query": "How did we fix the database locking issue?",
  "top_k": 3
}

3. mcp_graph-os_graph_query

Run read-only Cypher queries directly against the graph backend.

Example 1: Fetch all capabilities

{
  "cypher": "MATCH (r:CallableResource) RETURN r.name AS tool, r.resource_type AS type LIMIT 10",
  "scope": "local"
}

Example 2: Federated Query (External Graph)

{
  "cypher": "PREFIX foaf: <http://xmlns.com/foaf/0.1/> SELECT ?name WHERE { ?person foaf:name ?name } LIMIT 10",
  "scope": "federated",
  "reference_id": "EXTERNAL-WIKIDATA-01"
}

4. mcp_graph-os_graph_analyze

Run complex synthesis or comparative analysis across the Knowledge Graph.

Example 1: Blast Radius Calculation Determine the impact of changing a specific component.

{
  "action": "blast_radius",
  "node_id": "Code:auth.py",
  "depth": 2
}

Example 2: Security Scan Scan a subgraph for environment variables or exposed keys.

{
  "action": "security_scan",
  "target": "Codebase:frontend-app"
}

Example 3: Deep Extract Synthesize an executive summary of a concept's implementation.

{
  "action": "deep_extract",
  "target": "CONCEPT:AU-ORCH.routing.model-fallback-chain",
  "query": "Explain how the model fallback chain works."
}

5. mcp_graph-os_graph_write

Mutate the Knowledge Graph by adding nodes, edges, or logging chat memory.

Example 1: Log Chat Memory

{
  "action": "log_chat",
  "properties": "{\"user_prompt\": \"Add a login button\", \"resolution\": \"Button added in header.tsx\"}"
}

Example 2: Bulk Ingest Push a batch of telemetry or traces directly into the graph.

{
  "action": "bulk_ingest",
  "nodes": "[{\"id\": \"Trace-1\", \"label\": \"ExecutionTrace\"}]"
}

6. mcp_graph-os_graph_orchestrate

Dispatch subagents, handle consensus, and manage loop controls.

Example 1: Dispatch Subagent

{
  "agent_name": "repository-manager",
  "task": "Fix the linting errors in main.py",
  "max_steps": 5
}

Example 2: Validate a named skill through a real Pydantic graph

{
  "skill_name": "change-review",
  "tool_server": "itsm-api",
  "execution_mode": "pydantic_graph",
  "task": "Review one synthetic change and its approvals.",
  "allowed_tools": "get_change,list_approvals",
  "required_tools": "get_change,list_approvals"
}

Example 3: Spawn an agent with a curated handoff (CONCEPT:AU-ORCH.session.invoker-agent-handoff/1.39) Hand the spawned agent budgeted context, a least-privilege tool allow-list, a credential reference (resolved to a token at spawn, never logged), and open a message channel. The response is {"output", "mermaid", "channel_id"}.

{
  "agent_name": "github-mcp",
  "task": "List the latest workflow run for Knuckles-Team/agent-utilities",
  "context_ref": "ctx:sess-42:brief",
  "allowed_tools": "list_workflow_runs,get_workflow_run",
  "cred_ref": "cred:sess-42",
  "open_channel": true
}

7. mcp_graph-os_graph_configure

Manage backend configurations, system credentials, and tool registration.

Example 1: Set Secret

{
  "action": "set_secret",
  "config_key": "API_KEY_OPENAI",
  "config_value": "{\"token\": \"env://OPENAI_API_KEY\"}"
}

Example 2: Register MCP Hot-load a new MCP server without restarting the engine.

{
  "action": "register_mcp",
  "config_key": "custom-server",
  "config_value": "{\"command\": \"node\", \"args\": [\"server.js\"]}"
}

8. mcp_graph-os_graph_context

CONCEPT:AU-ORCH.session.invoker-agent-handoff — store/fetch curated context for an invoker→spawned-agent handoff, persisted in the epistemic-graph so a separately-spawned agent can read it by id. Session-anchored (AU-ORCH.session.session-anchored-collections-native): list is a reliable single-hop traversal from the Session node, isolated per session.

Example 1: Put a context blob

{
  "action": "put",
  "session_id": "sess-42",
  "key": "brief",
  "content": "Deployment target is compute-node. Use the 9B model. Read-only task."
}

Returns {"context_id": "ctx:sess-42:brief", "session_id": "sess-42"}. Pass that context_id to graph_orchestrate(context_ref="context:<opaque-id>").

Example 2: List all context for a session

{ "action": "list", "session_id": "sess-42" }

Example 3: Fetch one blob's full content by id

{ "action": "get", "context_id": "ctx:sess-42:brief" }

Example 4: Put an ephemeral blob with a TTL

{ "action": "put", "session_id": "sess-42", "key": "scratch", "content": "transient note", "ttl_s": 600 }

9. mcp_graph-os_graph_message

CONCEPT:AU-ORCH.session.session-anchored-collections-native — a bidirectional, cross-process, ordered message channel between an invoking agent and a spawned agent, over the engine's native Communication Channels (KG-2.0). The channel id is deterministic: orch:{session_id}:{run_id}.

Example 1: Open a channel

{ "action": "open", "session_id": "sess-42", "run_id": "run-abc1" }

Returns {"channel_id": "orch:sess-42:run-abc1"}. (Or pass open_channel=true to graph_orchestrate(open_channel=true) and read channel_id from its response.)

Example 2: Send a message (the sender auto-joins)

{ "action": "send", "channel_id": "orch:sess-42:run-abc1", "sender": "invoker", "payload": "proceed with the task" }

Example 3: Send a durable message (survives engine restart)

{ "action": "send", "channel_id": "orch:sess-42:run-abc1", "sender": "invoker", "payload": "final instruction", "durable": true }

Example 4: Receive new messages with a cursor since is the count already consumed; the response returns {"messages", "cursor"} — pass the returned cursor as since on the next poll.

{ "action": "receive", "channel_id": "orch:sess-42:run-abc1", "since": 0 }

Example 5: Replay the durable history (id-anchored, restart-safe)

{ "action": "history", "channel_id": "orch:sess-42:run-abc1" }

Example 6: Close the channel

{ "action": "close", "channel_id": "orch:sess-42:run-abc1" }