MCP Tools Reference

Complete reference for all 9 MCP tools available to AI agents.

Overview

Epitome exposes 9 tools through the Model Context Protocol (MCP). These tools allow any MCP-compatible AI agent to read and write your personal data, search memories, explore the knowledge graph, and log activity. All tools require authentication and are subject to the consent system.

read_profileupdate_profilequery_tableinsert_recordsearch_memorystore_memoryquery_graphget_entity_neighborslog_activity

Transport & Authentication

The MCP server uses Streamable HTTP transport for the hosted service. Agents authenticate using their MCP URL token, which maps to an API key and user account. The server validates each request and checks the agent's consent grants before executing any tool.

If an agent calls a tool for a resource it has not been granted consent to access, the server returns a consent-required error with instructions for the user to grant permission via the dashboard.

read_profile

Read the user's complete profile, including name, timezone, preferences, family, work, health, and any other stored profile data. This should be called at the start of every conversation to personalize the interaction.

This tool takes no parameters.

Returns: The full profile JSONB document with version number, confidence score, and last-updated timestamp.

json

// Example response
{
  "version": 12,
  "confidence": 0.87,
  "updated_at": "2026-02-15T10:30:00Z",
  "data": {
    "name": "Alice Chen",
    "timezone": "America/Los_Angeles",
    "preferences": {
      "food": { "favorites": ["sushi", "pad thai"], "regional_style": "Pacific Northwest" }
    },
    "family": [
      { "name": "Bob", "relation": "spouse" },
      { "name": "Emma", "relation": "daughter", "birthday": "2019-03-15" }
    ],
    "career": {
      "primary_job": { "title": "Staff Engineer", "company": "Acme Corp" }
    }
  }
}

update_profile

Update one or more fields in the user's profile. Uses deep merge — only the specified fields are changed; all other data is preserved. Creates a new profile version for history tracking.

Name	Type	Required	Description
data	object	Yes	An object containing the profile fields to update. Supports nested paths via dot notation or nested objects.

json

// Example: update timezone and add a food preference
{
  "data": {
    "timezone": "America/New_York",
    "preferences": {
      "food": {
        "favorites": ["sushi", "pad thai", "pizza"]
      }
    }
  }
}

query_table

Query records from one of the user's custom tables. Tables are user-defined structured collections (e.g., 'reading_list', 'projects', 'recipes'). Returns matching records with pagination support.

Name	Type	Required	Description
table	string	Yes	Name of the table to query (e.g., "reading_list", "habits").
filters	object	No	Key-value pairs to filter records. Keys are column names, values are the expected values.
limit	number	No	Maximum number of records to return (default: 50, max: 200).
offset	number	No	Number of records to skip for pagination (default: 0).

json

// Example: query the reading list for unread books
{
  "table": "reading_list",
  "filters": { "status": "unread" },
  "limit": 10
}

// Example response
{
  "records": [
    { "id": "rec_001", "title": "Dune", "author": "Frank Herbert", "status": "unread" },
    { "id": "rec_002", "title": "Neuromancer", "author": "William Gibson", "status": "unread" }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

insert_record

Insert a new record into one of the user's custom tables. If the table does not exist, it is automatically created with the schema inferred from the first record's fields.

Name	Type	Required	Description
table	string	Yes	Name of the table to insert into. Created automatically if it does not exist.
data	object	Yes	The record data as key-value pairs. Keys become column names.

json

// Example: add a book to the reading list
{
  "table": "reading_list",
  "data": {
    "title": "Snow Crash",
    "author": "Neal Stephenson",
    "status": "unread",
    "added_date": "2026-02-17"
  }
}

// Example response
{
  "id": "rec_003",
  "table": "reading_list",
  "data": {
    "title": "Snow Crash",
    "author": "Neal Stephenson",
    "status": "unread",
    "added_date": "2026-02-17"
  },
  "created_at": "2026-02-17T14:20:00Z"
}

search_memory

Perform semantic vector search across the user's stored memories. Uses pgvector cosine similarity to find memories that are conceptually related to the query, even if they don't share exact keywords. Essential for personalized recommendations and context-aware responses.

Name	Type	Required	Description
query	string	Yes	The natural-language search query. Converted to a vector embedding for similarity search.
collection	string	No	Limit search to a specific vector collection (e.g., "conversations", "facts"). Omit to search all collections.
limit	number	No	Maximum number of results to return (default: 10, max: 50).
min_similarity	number	No	Minimum cosine similarity threshold, from 0 to 1 (default: 0.3). Higher values return fewer but more relevant results.

json

// Example: search for outdoor activity memories
{
  "query": "outdoor hobbies and activities",
  "limit": 5,
  "min_similarity": 0.4
}

// Example response
{
  "results": [
    {
      "id": "vec_001",
      "content": "I love hiking in the Cascades, especially the PCT section near Snoqualmie Pass.",
      "collection": "interests",
      "similarity": 0.89,
      "metadata": { "source": "claude-desktop" },
      "created_at": "2026-02-10T09:15:00Z"
    },
    {
      "id": "vec_002",
      "content": "Started rock climbing at the local gym three times a week.",
      "collection": "activities",
      "similarity": 0.72,
      "metadata": { "source": "chatgpt" },
      "created_at": "2026-01-28T16:45:00Z"
    }
  ]
}

store_memory

Store a new memory as a vector embedding. The content is automatically embedded using text-embedding-3-small and stored in pgvector for semantic search. Also triggers async entity extraction to update the knowledge graph.

Name	Type	Required	Description
content	string	Yes	The text content of the memory to store. Should be a meaningful statement or fact about the user.
collection	string	No	The vector collection to store in (e.g., "facts", "preferences", "conversations"). Defaults to "general".
metadata	object	No	Optional metadata to attach (e.g., source agent, conversation ID, tags).

json

// Example: store a new memory
{
  "content": "My daughter Emma starts kindergarten in September 2026 at Lincoln Elementary.",
  "collection": "family",
  "metadata": {
    "source": "claude-desktop",
    "conversation_id": "conv_abc123"
  }
}

// Example response
{
  "id": "vec_003",
  "content": "My daughter Emma starts kindergarten in September 2026 at Lincoln Elementary.",
  "collection": "family",
  "confidence": 0.95,
  "entities_extracted": ["Emma", "Lincoln Elementary"],
  "created_at": "2026-02-17T14:30:00Z"
}

query_graph

Query entities in the user's knowledge graph. The graph contains people, places, organizations, and concepts extracted from memories, with typed edges representing relationships between them.

Name	Type	Required	Description
entity_type	string	No	Filter by entity type: "person", "place", "organization", "concept", "event". Omit to return all types.
name	string	No	Filter entities by name (case-insensitive substring match).
limit	number	No	Maximum number of entities to return (default: 50, max: 200).

json

// Example: find all people in the graph
{
  "entity_type": "person",
  "limit": 20
}

// Example response
{
  "entities": [
    {
      "id": "ent_001",
      "name": "Emma",
      "type": "person",
      "properties": { "relation": "daughter", "age": 6 },
      "mention_count": 12,
      "first_seen": "2026-01-05T10:00:00Z",
      "last_seen": "2026-02-17T14:30:00Z"
    },
    {
      "id": "ent_002",
      "name": "Bob",
      "type": "person",
      "properties": { "relation": "spouse" },
      "mention_count": 8,
      "first_seen": "2026-01-05T10:00:00Z",
      "last_seen": "2026-02-15T09:20:00Z"
    }
  ]
}

get_entity_neighbors

Get all entities connected to a specific entity in the knowledge graph. Returns the entity's direct neighbors along with the typed edges connecting them. Useful for exploring relationships and building context about a person, place, or concept.

Name	Type	Required	Description
entity_id	string	Yes	The ID of the entity whose neighbors to retrieve.

json

// Example: get neighbors of Emma
{
  "entity_id": "ent_001"
}

// Example response
{
  "entity": {
    "id": "ent_001",
    "name": "Emma",
    "type": "person",
    "properties": { "relation": "daughter", "age": 6 }
  },
  "neighbors": [
    {
      "entity": { "id": "ent_002", "name": "Bob", "type": "person" },
      "edge": { "type": "family_member", "direction": "outgoing", "properties": { "relation": "father" } }
    },
    {
      "entity": { "id": "ent_005", "name": "Lincoln Elementary", "type": "organization" },
      "edge": { "type": "attends", "direction": "outgoing", "properties": { "start_date": "2026-09" } }
    }
  ]
}

log_activity

Log an activity entry to the user's audit trail. Use this to record significant actions taken by the agent, such as making recommendations, updating records, or performing research. Helps the user track what their AI agents have been doing.

Name	Type	Required	Description
action	string	Yes	A short description of the action performed (e.g., "recommended_recipe", "updated_reading_list").
details	object	No	Optional additional details about the action (e.g., what was recommended, what changed).

json

// Example: log a recommendation action
{
  "action": "recommended_recipe",
  "details": {
    "recipe": "Salmon Teriyaki Bowl",
    "reason": "Matches user's preference for Pacific Northwest cuisine and fish",
    "dietary_check": "no known allergies"
  }
}

// Example response
{
  "id": "act_001",
  "agent_id": "agent_claude_desktop",
  "action": "recommended_recipe",
  "details": { ... },
  "created_at": "2026-02-17T14:35:00Z"
}

Quick Start API Reference