Graph MCP Tools

Five MCP tools expose the knowledge graph to agents and operators through the platform's JSON-RPC MCP endpoint. The live MCP transport checks the per-project gate - isGraphEnabledForProject(orgId, projectId), i.e. the project's memory must be enabled and graph must be on (explicit project_memory_config.graph_enabled or a plan that grants kg_enabled) - and enforces Cedar authorization before executing. When the project's memory is off or graph is off, the transport refuses the graph tools (and recall-graph): the caller receives a uniform { disabled: true } response without error. See Knowledge Graph Store → Per-project enablement.

Tool reference

`graph_query`

Runs GRAPH_COMPLETION: embeds the query, finds nearest nodes in the vector index, expands k-hop neighborhoods, and returns ranked (source, relationship, target) triplets.

Input:

{
  "query": "How does authentication interact with the user service?",
  "topK": 10,
  "neighborhoodDepth": 2,
  "context": {
    "agentId": "agent_...",
    "orgId": "org_...",
    "projectId": "proj_..."
  }
}

Field	Type	Default	Description
`query`	`string`	required	Natural-language search phrase
`topK`	`number`	`10`	Maximum seed nodes from vector search
`neighborhoodDepth`	`number`	`2`	Hops to expand from each seed
`context.agentId`	`string`	required	Caller agent identity for Cedar
`context.orgId`	`string`	required	Tenant scope
`context.projectId`	`string`	required	Project scope
`context.sessionId`	`string`	optional	Used in audit events

Output:

{
  "triplets": [
    {
      "sourceEntity": "AuthService",
      "relationship": "calls",
      "targetEntity": "UserRepository",
      "relevanceScore": 0.12,
      "provenance": {
        "observationId": "obs_...",
        "sessionId": "sess_...",
        "timestamp": "2026-05-30T14:22:00Z"
      }
    }
  ]
}

Cedar PEP is applied to both endpoint nodes of each triplet. Triplets with denied endpoints are silently excluded.

`graph_neighbors`

Returns the k-hop neighborhood of a named entity. Accepts an entity name or UUID. Supports optional relationship filtering.

Input:

{
  "entity": "AuthService",
  "depth": 1,
  "relationshipFilter": "depends_on",
  "context": { "agentId": "...", "orgId": "...", "projectId": "..." }
}

Field	Type	Default	Description
`entity`	`string`	required	Entity name or UUID
`depth`	`number`	`1`	Hops to expand
`relationshipFilter`	`string`	none	Restrict to this relationship type

Output:

{
  "nodes": [
    {
      "id": "uuid",
      "name": "PostgresDB",
      "type": "Database",
      "description": "Primary application database",
      "provenance": { "observationId": "obs_...", "sessionId": null }
    }
  ],
  "edges": [
    {
      "sourceId": "uuid-auth",
      "targetId": "uuid-db",
      "relationshipName": "depends_on"
    }
  ]
}

Cedar PEP filters both nodes and edges. Edges referencing at least one denied node are excluded.

`graph_path`

Finds the shortest path between two named entities using BFS traversal.

Input:

{
  "fromEntity": "UserController",
  "toEntity": "PostgresDB",
  "maxDepth": 6,
  "context": { "agentId": "...", "orgId": "...", "projectId": "..." }
}

Returns the PathResult (ordered nodes and edges along the path) or null if no path exists within maxDepth.

`graph_ingest`

Admin tool. Triggers the extraction pipeline on recent unprocessed observations. Pulls up to limit observations and runs extractAndStore on each.

graph_ingest requires write authorization (write_node Cedar action) on the org/project scope. A Cedar deny short-circuits the entire batch - no partial population.

Input:

{
  "limit": 20,
  "context": { "agentId": "...", "orgId": "...", "projectId": "..." }
}

Output:

{
  "processed": 18,
  "totalNodesCreated": 42,
  "totalEdgesCreated": 67,
  "mergedCount": 11
}

The mergedCount field counts entity resolution merges - nodes that resolved to an existing UUID rather than being inserted fresh. A non-zero merge count is healthy (deduplication working).

`graph_improve`

Admin tool. Applies session-outcome feedback to the knowledge graph. Updates feedbackWeight via EMA on every referenced node and edge.

graph_improve requires write authorization. A deny short-circuits with zero updates.

Input:

{
  "sessionId": "sess_...",
  "outcome": "accepted",
  "usedNodeIds": ["node-uuid-1", "node-uuid-2"],
  "usedEdgeKeys": [
    {
      "sourceId": "node-uuid-1",
      "targetId": "node-uuid-2",
      "relationshipName": "depends_on"
    }
  ],
  "context": { "agentId": "...", "orgId": "...", "projectId": "..." }
}

`outcome`	Effect on `feedbackWeight`
`accepted`	EMA toward `1.0` - entity was useful
`rework`	EMA toward `0.5` - entity needed correction
`rejected`	EMA toward `0.0` - entity was unhelpful

Output:

{
  "nodeUpdates": 2,
  "edgeUpdates": 1,
  "tripletEmbeddings": 1,
  "durationMs": 34
}

tripletEmbeddings is 0 when no VOYAGE_API_KEY is configured.

Common behavior

All five tools share the same guard sequence:

1. Check per-project gate isGraphEnabledForProject(orgId, projectId)
   (project memory enabled AND graph on) → { disabled: true } if off
2. Authorize via Cedar PEP (verb varies by tool)
3. Execute operation
4. Filter results via Cedar PEP (read tools only)

The context object passed by the agent is the Cedar identity. agentId, orgId, and projectId are required; sessionId is optional but recorded in audit events.

Using graph tools from an agent card

# agent-card.yaml (excerpt)
mcpTools:
  - graph_query
  - graph_neighbors
  - graph_path

Write tools (graph_ingest, graph_improve) should only be added to privileged operator agent cards, not to standard SDLC agents.

Hybrid Search - search modes used internally by the tools
Graph Feedback - the service behind graph_improve
Extraction Pipeline - what graph_ingest triggers
Context Injection - automatic graph context (no tool needed)
Cedar Policies - authorization model

On this page