Documentation

MCP API Reference

Give your AI agents persistent memory through the Model Context Protocol. Connect any MCP-compatible client to start storing and retrieving memories.

Auto-discovery

MCP-compatible agents automatically discover all available tools when they connect to the server. You don't need to manually configure which tools to use — your agent will see the full list of tools, their descriptions, and parameter schemas as soon as it connects.

Endpoint

POST https://agimem.dev/api/mcp

agimem uses Streamable HTTP transport (not SSE). The endpoint accepts standard JSON-RPC over HTTP. Batch JSON-RPC requests are not supported.

Authentication

All requests require a Bearer token. Use the API key from your capsule — each key is scoped to exactly one capsule.

Authorization: Bearer mcp_your_api_key

Client Configuration

Add the following to your MCP client configuration (e.g. Claude Desktop, Cursor, VS Code, Windsurf):

{
  "mcpServers": {
    "agimem": {
      "url": "https://agimem.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer mcp_your_api_key"
      }
    }
  }
}

See the Integrations page for client-specific setup guides.

Permissions

Each API key has a role that controls which tools it can call. Attempting to call a tool without the required permission returns an error.

Role	Allowed tools
`read`	All read tools only
`write`	All read + write tools

Rate Limits

60 requests per minute per account, shared across MCP and REST. Rate limited responses return a JSON-RPC error.

Memory Tools

writememory_setStore a value under a key in the Capsule

Store a value under a key in the Capsule

Parameters

keyrequiredThe key to store the value under (max 256 chars)

valuerequiredThe value to store (max 50,000 chars)

tagsOptional array of tags (up to 5). Passing an empty array clears existing tags.

ttlMinutesOptional time-to-live in minutes (1–525,600). Omit for non-expiring memory.

readmemory_getRetrieve a value by key from the Capsule

Retrieve a value by key from the Capsule

Parameters

keyrequiredThe key to retrieve

writememory_deleteDelete a key-value pair from the Capsule

Delete a key-value pair from the Capsule

Parameters

keyrequiredThe key to delete

readmemory_existsCheck whether a key exists in the Capsule without fetching its value

Check whether a key exists in the Capsule without fetching its value

Parameters

keyrequiredThe key to check

readmemory_searchSearch for memories by key or value containing the query string (case-insensitive)

Search for memories by key or value containing the query string (case-insensitive)

Parameters

queryrequiredThe search query to match against memory keys and values (max 500 chars)

limitMaximum results to return (default 20, max 50)

readmemory_countReturn the number of non-expired memories in the Capsule

Return the number of non-expired memories in the Capsule

readmemory_keysList only the keys in the Capsule (no values). Lighter than memory_list when you just need key names.

List only the keys in the Capsule (no values). Lighter than memory_list when you just need key names.

readmemory_listList keys in the Capsule (paginated). Returns page info with totalCount and totalPages.

List keys in the Capsule (paginated). Returns page info with totalCount and totalPages.

Parameters

pagePage number (default 1)

pageSizeItems per page (default 50, max 200)

writememory_clearDelete all key-value pairs in the Capsule

Delete all key-value pairs in the Capsule

Bulk Tools

writememory_bulk_setStore multiple key-value pairs in a single call (up to 20 items)

Store multiple key-value pairs in a single call (up to 20 items)

Parameters

itemsrequiredArray of { key, value, tags?, ttlMinutes? } objects (1–20)

readmemory_bulk_getRetrieve multiple values by key in a single call (up to 50 keys)

Retrieve multiple values by key in a single call (up to 50 keys)

Parameters

keysrequiredArray of keys to retrieve (1–50)

writememory_bulk_deleteDelete multiple key-value pairs in a single call (up to 50 keys)

Delete multiple key-value pairs in a single call (up to 50 keys)

Parameters

keysrequiredArray of keys to delete (1–50)

Tag Tools

readmemory_list_by_tagList all keys in the Capsule that have a given tag

List all keys in the Capsule that have a given tag

Parameters

tagrequiredTag to filter memories by

readmemory_list_by_tagsList keys that match ALL of the given tags (AND filter)

List keys that match ALL of the given tags (AND filter)

Parameters

tagsrequiredArray of tags — returns only keys that have ALL of these tags

writetag_createCreate a new capsule-level tag

Create a new capsule-level tag

Parameters

namerequiredTag name to create

readtag_listList all tags in the Capsule

List all tags in the Capsule

writetag_deleteDelete a tag from the Capsule and unlink it from memories

Delete a tag from the Capsule and unlink it from memories

Parameters

namerequiredTag name to delete

Capsule Tools

readcapsule_infoGet a summary of the current Capsule: name, memory count, tag count, limits, and last activity

Get a summary of the current Capsule: name, memory count, tag count, limits, and last activity