MCP

How do I connect an AI agent to Areev via MCP?

Start the server with --mcp and point any MCP-compatible client at the /mcp endpoint. MCP is the fastest way to give an AI agent autonomous memory capabilities through Areev.

The Model Context Protocol (MCP) gives AI agents direct access to the Areev context database through a standardized tool-calling interface. When an agent connects, the MCP server advertises a filtered set of the 12 available tools plus 3 resources. Clients like Claude Desktop, Cursor, and other MCP-compatible frameworks discover these tools automatically and can invoke them within their normal conversation flow.

Authentication is handled at the MCP transport layer rather than through per-request headers, so agents do not need to manage API keys or tokens. The AI agent memory operations exposed through MCP are the same operations available through the REST API and CLI, with response formats optimized for the MCP protocol’s tool-result structure.

To enable MCP, pass --mcp to areev serve. The server listens for MCP connections on the same HTTP port as the REST API, at the /mcp path.

# Start with MCP enabled
areev serve --mcp --http 0.0.0.0:4009

{
  "mcpServers": {
    "areev": {
      "url": "http://localhost:4009/mcp"
    }
  }
}

How do I control which tools my agent sees?

Areev uses composable tag filtering so your agent only sees the tools it needs. Clients with too many tools exposed experience measurable tool-selection degradation past ~20; Areev keeps the default surface small.

Five tag groups compose the full 12-tool surface. The default /mcp URL exposes only the 5-tool core set. Widen the surface by enumerating additional tags as a query parameter:

{
  "mcpServers": {
    "areev-core":      { "url": "http://localhost:4009/mcp" },
    "areev-with-cal":  { "url": "http://localhost:4009/mcp?tags=core,cal" },
    "areev-full":      { "url": "http://localhost:4009/mcp?tags=core,ingest,retrieval,write,cal" }
  }
}

Two extra query parameters refine the set after resolution:

• include_tools=areev_cal,areev_search — adds specific tools on top of the tag-resolved set.
• exclude_tools=areev_forget — removes specific tools from the set.

Resolution order is tags → +include_tools → −exclude_tools. Unknown tags or unknown tool names return a JSON-RPC -32602 Invalid params error so misconfigured clients fail fast. There is no wildcard — to expose every tool, enumerate every tag.

The initialize response advertises tools.tags_available, tools.tags_active, and tools.tool_tags so agent-facing UIs can render a ”+ add capability” control without consulting this doc.

Tools outside the active tag set are rejected at tools/call with -32601 Method not found, even if the client attempts to invoke them directly.

What tools does the MCP server expose?

The server exposes 12 tools: areev_recall, areev_remember, areev_supersede, areev_action_list, areev_action_invoke (core), areev_add (ingest), areev_search, areev_inspect, areev_recall_chain (retrieval), areev_accumulate, areev_forget (write), and areev_cal (cal).

areev_recall queries memories with free-text BM25 search, structural filters (subject, relation, object), or hybrid search combining both. The scope_path parameter targets specific parts of a multi-tenant hierarchy, and include_siblings widens the search to sibling namespaces. areev_recall_chain decomposes a complex question into sub-queries, executes each independently, and merges the results (requires a language model for decomposition).

areev_remember ingests natural language text as memory, creating an Observation grain and queuing belief extraction (use sync=true for inline LLM extraction). areev_add stores a structured grain directly — the grain_type defaults to belief if omitted. Each grain type has required fields: beliefs need subject/relation/object; events need content; states need data (object); workflows need nodes, edges, bindings, retries; actions need tool_name; observations need content; goals need description; consent needs subject_did and user_id. Optional common fields include namespace, tags (array), confidence (0.0-1.0), and user_id.

areev_forget deletes a grain by its content-address hash, supporting GDPR erasure. areev_inspect retrieves a grain by hash with an optional memory_id. areev_search performs full-text search across all grain content. areev_supersede merges new fields over an existing grain while preserving unspecified fields and the grain type. areev_accumulate atomically applies numeric deltas to a grain’s fields with tip resolution (zero conflicts). areev_cal executes CAL (Context Assembly Language) queries supporting RECALL, ASSEMBLE, BATCH, COALESCE, HISTORY, EXISTS, EXPLAIN, DESCRIBE, and FORMAT operations.

areev_action_list lists bound tool definitions for a harness, rendered in MCP tools/list shape, so external agents can treat Areev as a tool catalog. areev_action_invoke invokes a bound tool by name, validates arguments against its input schema, dispatches via Axtion, persists an Execution Action grain, and emits an ActionInvoked audit entry.

{
  "name": "areev_add",
  "arguments": {
    "grain_type": "belief",
    "fields": {
      "subject": "rust",
      "relation": "created_by",
      "object": "Graydon Hoare",
      "confidence": 0.99,
      "namespace": "programming",
      "tags": ["languages", "history"]
    }
  }
}

{
  "name": "areev_recall",
  "arguments": {
    "query": "programming languages",
    "subject": "rust",
    "limit": 5,
    "scope_path": "acme/prod",
    "include_siblings": true
  }
}

{
  "name": "areev_supersede",
  "arguments": {
    "hash": "a3f8c1...",
    "fields": {"object": "updated value", "confidence": 0.99}
  }
}

What about stats, PII detection, metrics, and provenance?

Those surfaces are available through REST and gRPC, not MCP. Operator telemetry and pipeline-stage utilities are not agent tools — exposing them on MCP crowded the active tool list without serving agent workflows.

The equivalent endpoints are:

Three MCP resources remain available and are unaffected by tag filtering: areev://grains lists recent grains, areev://stats returns database statistics, and areev://compliance returns the latest compliance verification results.

How does MCP differ from the REST API?

MCP tools operate on the default memory instance and return SearchHit format, while the REST API uses ConsoleGrainResponse and requires an explicit memory_id path parameter.

The MCP interface is designed for AI agent integration where the agent framework manages the connection lifecycle. The REST API is designed for programmatic access from application code. In practice, this means MCP clients get a streamlined tool schema that hides instance routing, while REST clients get full control over multi-instance deployments.

Specific differences: areev_recall returns SearchHit with fields_json, while REST /recall returns ConsoleGrainResponse with flat fields. areev_stats returns a simplified {total_grains, disk_space_bytes} object, while REST /stats returns the full ConsoleStatsResponse with type counts, metrics, and history. areev_supersede auto-fetches the old grain and merges new fields, while REST /supersede requires you to send the full grain type and fields. MCP transport handles authentication at the connection level, so individual tool calls carry no auth headers.

Related

• A2A — Agent-to-Agent protocol (alternative agent integration)
• HTTP REST — direct REST API with full endpoint coverage
• CLI — enable MCP with areev serve --mcp