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 15 tools and 3 resources that cover grain CRUD, search, compliance, ingest, and metrics. Clients like Claude Desktop, Cursor, and other MCP-compatible frameworks discover these tools automatically and can invoke them within their normal conversation flow.
All MCP tools operate on the default memory instance. 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"
}
}
}What tools does the MCP server expose?
The server exposes 15 tools: areev_add, areev_recall, areev_recall_chain, areev_forget, areev_inspect, areev_search, areev_supersede, areev_accumulate, areev_cal, areev_stats, areev_detect_pii, areev_remember, areev_flush, areev_metrics, and areev_provenance.
areev_add stores a grain in the context database. 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_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_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_remember ingests natural language text as memory, creating an Observation grain and queuing belief extraction (use sync=true for inline LLM extraction). areev_flush flushes the write buffer, ensuring all pending writes are committed to storage. areev_provenance lists decision provenance records from recall operations for AI decision auditing (EU AI Act Art. 86).
{
"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}
}
}| grain_type | Required fields |
|---|---|
belief | subject, relation, object |
event | content |
state | data (object) |
workflow | nodes (array of strings), edges (array of {from,to,condition?}), bindings (object), retries (object) |
action | tool_name |
observation | content |
goal | description |
reasoning | (none) |
consensus | (none) |
consent | subject_did, user_id |
What monitoring and compliance tools are available?
The areev_stats, areev_detect_pii, areev_metrics, and areev_provenance tools provide database statistics, PII scanning, operational health monitoring, and decision audit trails.
areev_stats returns total grain count and disk space in bytes. This is a lightweight call suitable for periodic health checks without significant load on the autonomous memory engine.
areev_detect_pii runs the hybrid NER + regex pipeline on a text string and returns match categories, positions, and confidence scores. All processing runs locally with no data sent to external services. areev_metrics returns operational health, intelligence quality, and billing metrics for a specified domain (ops, intel, billing, or all). areev_provenance lists decision provenance records from recall operations, returning the transparency trail for AI decision auditing (EU AI Act Art. 86).
Three MCP resources provide read-only data that agents can access without a tool call: areev://grains lists recent grains, areev://stats returns database statistics, and areev://compliance returns the latest compliance verification results.
{"name": "areev_stats", "arguments": {}}{"name": "areev_detect_pii", "arguments": {"text": "Contact john@example.com at 555-0100"}}{"name": "areev_metrics", "arguments": {"domain": "ops"}}| Domain | Contents |
|---|---|
ops | Subsystem health, counters, latency |
intel | Intelligence and quality scores |
billing | Usage and cost metrics |
all | All domains combined (default) |
| Resource URI | MIME type | Description |
|---|---|---|
areev://grains | application/json | List of recent grains in the database |
areev://stats | application/json | Database statistics (grain count, disk space) |
areev://compliance | application/json | 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.