MCP Tools
LocusGraph currently exposes four MCP tools through the region server, with OAuth enforced at the auth worker's /mcp endpoint.
Scopes
OAuth scopes are enforced before the request reaches the graph:
| Tool | Required scopes |
|---|---|
retrieve_memories | memory.read |
list_contexts | memory.read |
store_event | memory.read, memory.write |
generate_insights | memory.read, memory.write |
The access token is also bound to the selected graph_id, and the auth worker forwards that graph to the region server via X-Graph-Id.
store_event
Writes knowledge into the wisdom graph. The admission pipeline processes the event into a locus automatically.
Parameters:| Name | Required | Description |
|---|---|---|
event_kind | Yes | Event kind: fact, action, decision, observation, feedback |
payload | No | Memory payload. Recommended shape: { "data": { "topic": "...", "value": "..." } } |
context_id | No | Primary context in format type:name |
source | No | Event source: agent, user, system, validator, executor |
reinforces | No | Array of context IDs this event reinforces |
extends | No | Array of context IDs this event extends |
contradicts | No | Array of context IDs this event contradicts |
related_to | No | Array of related context IDs |
timestamp | No | Unix timestamp as string |
Aliases accepted by the backend:
context_id: also acceptsevent_idevent_kind: also acceptsevent_typeandeventTypepayload: also acceptscontent
{
"tool": "store_event",
"arguments": {
"context_id": "skill:react_hooks",
"event_kind": "fact",
"source": "agent",
"payload": {
"topic": "useEffect cleanup", "value": "Always return a cleanup function when subscribing to external stores"
}
}
}retrieve_memories
Searches the wisdom graph using semantic similarity and returns ranked results.
Parameters:| Name | Required | Description |
|---|---|---|
query | Yes | Search query string |
limit | No | Maximum number of results |
context_ids | No | Filter by specific context IDs |
context_types | No | Filter by context types (map of type to names) |
include_ids | No | Include locus IDs and context IDs in the response |
{
"tool": "retrieve_memories",
"arguments": {
"query": "React hook best practices",
"limit": 5,
"context_types": { "skill": ["react_hooks"] }
}
}list_contexts
Lists available context IDs with optional filtering and pagination.
Parameters:| Name | Required | Description |
|---|---|---|
context_type | No | Filter by context type |
context_name | No | Filter by context name |
limit | No | Max results. Default: 100 |
page | No | Pagination page. Default: 0 |
{
"tool": "list_contexts",
"arguments": {
"context_type": "skill",
"limit": 10
}
}generate_insights
Analyzes stored knowledge and generates insights for a given task.
Parameters:| Name | Required | Description |
|---|---|---|
task | Yes | Task description for insight generation |
locus_query | No | Query for searching relevant knowledge |
limit | No | Maximum number of knowledge items to retrieve |
context_ids | No | Filter by specific context IDs |
context_types | No | Filter by context types |
The backend also accepts context_query as an alias for locus_query.
{
"tool": "generate_insights",
"arguments": {
"task": "Refactor the authentication module",
"locus_query": "authentication patterns and past errors",
"limit": 10,
"context_types": { "error": [], "skill": [] }
}
}tools/list is discoverable over MCP, but tools/call uses OAuth access tokens issued by the auth worker, not direct LOCUSGRAPH_AGENT_SECRET configuration.