MCP Tools Reference

MCP Tools Reference

Cortex exposes memory primitives as MCP tools. Any MCP-compatible client can discover and use these tools through the standard protocol.

Discovery

MCP clients discover available tools during the handshake. Cortex returns tool schemas that describe parameters, types, and expected responses.

Example tool listing (truncated):

{
  "tools": [
    {
      "name": "knowledge_search",
      "description": "Search the knowledge store with hybrid vector + full-text matching",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Search query" },
          "collection": { "type": "string", "description": "Optional collection filter" },
          "mode": { "type": "string", "enum": ["vector", "fts", "hybrid"] },
          "limit": { "type": "integer", "default": 10 }
        },
        "required": ["query"]
      }
    }
  ]
}

---

Conversation Tools

conversation_append

Add a message to a conversation thread.

Parameters:

Name	Type	Required	Description
thread_id	string	Yes	Unique thread identifier
role	string	Yes	Message role: user, assistant, system, tool
content	string	Yes	Message content
metadata	object	No	Additional metadata (tool calls, citations, etc.)

Response:

{
  "message_id": "msg_abc123",
  "thread_id": "support-ticket-456",
  "created_at": "2024-01-15T10:30:00Z"
}

Example:

{
  "tool": "conversation_append",
  "arguments": {
    "thread_id": "support-ticket-456",
    "role": "user",
    "content": "I can't access my account"
  }
}

---

conversation_history

Retrieve conversation history for a thread.

Parameters:

Name	Type	Required	Description
thread_id	string	Yes	Thread identifier
limit	integer	No	Maximum messages (default: 50)
before	string	No	ISO timestamp, return messages before this
after	string	No	ISO timestamp, return messages after this

Response:

{
  "thread_id": "support-ticket-456",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "I can't access my account",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "I'd be happy to help. Can you provide your email?",
      "created_at": "2024-01-15T10:30:15Z"
    }
  ],
  "has_more": false
}

---

conversation_search

Semantic search across conversation messages.

Parameters:

Name	Type	Required	Description
query	string	Yes	Search query
thread_id	string	No	Limit to specific thread
namespace	string	No	Namespace filter
limit	integer	No	Maximum results (default: 10)

Response:

{
  "results": [
    {
      "message_id": "msg_789",
      "thread_id": "support-ticket-456",
      "role": "user",
      "content": "I can't access my account after password reset",
      "score": 0.89,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

---

conversation_summarize

Summarize and compress conversation history.

Parameters:

Name	Type	Required	Description
thread_id	string	Yes	Thread to summarize
keep_recent	integer	No	Number of recent messages to keep uncompressed

Response:

{
  "thread_id": "support-ticket-456",
  "summary": "User reported account access issues after password reset. Agent verified identity and initiated manual unlock.",
  "original_count": 45,
  "compressed_count": 12
}

---

Knowledge Tools

knowledge_ingest

Ingest a document into the knowledge store.

Parameters:

Name	Type	Required	Description
collection	string	Yes	Target collection
title	string	Yes	Document title
content	string	Yes	Document content
source_url	string	No	Original source URL
metadata	object	No	Additional metadata
chunk_strategy	string	No	fixed, sentence, paragraph, semantic
chunk_max_tokens	integer	No	Maximum tokens per chunk
chunk_overlap	integer	No	Token overlap between chunks

Response:

{
  "document_id": "doc_abc123",
  "collection": "docs",
  "chunks_created": 12,
  "total_tokens": 3500
}

---

knowledge_bulk_ingest

Batch ingest multiple documents.

Parameters:

Name	Type	Required	Description
collection	string	Yes	Target collection
documents	array	Yes	Array of document objects

Each document in the array:

Name	Type	Required	Description
title	string	Yes	Document title
content	string	Yes	Document content
source_url	string	No	Original source URL
metadata	object	No	Additional metadata

Response:

{
  "collection": "docs",
  "documents_ingested": 15,
  "total_chunks": 180,
  "errors": []
}

---

knowledge_search

Search the knowledge store with hybrid matching.

Parameters:

Name	Type	Required	Description
query	string	Yes	Search query
collection	string	No	Limit to collection
mode	string	No	vector, fts, or hybrid (default)
limit	integer	No	Maximum results (default: 10)
threshold	number	No	Minimum similarity score
metadata_filter	object	No	Filter by metadata fields

Response:

{
  "results": [
    {
      "chunk_id": "chunk_456",
      "document_id": "doc_abc123",
      "title": "Authentication Guide",
      "content": "To configure OAuth, first create an application...",
      "score": 0.92,
      "metadata": {
        "category": "authentication"
      }
    }
  ],
  "search_mode": "hybrid"
}

---

knowledge_collections

Manage collections.

Parameters:

Name	Type	Required	Description
action	string	Yes	list, create, delete, stats
name	string	Conditional	Required for create, delete, stats
description	string	No	For create action

Response (list):

{
  "collections": [
    {
      "name": "docs",
      "description": "Product documentation",
      "document_count": 45,
      "chunk_count": 890
    }
  ]
}

---

Context Tools

context_get

Retrieve a value by key.

Parameters:

Name	Type	Required	Description
key	string	Yes	Key to retrieve
run_id	string	No	Scope to specific run

Response:

{
  "key": "config/debug",
  "value": {"enabled": true, "level": "verbose"},
  "version": 3,
  "expires_at": null,
  "updated_at": "2024-01-15T10:30:00Z"
}

---

context_set

Store a value.

Parameters:

Name	Type	Required	Description
key	string	Yes	Key to set
value	any	Yes	Value to store (JSON)
ttl_seconds	integer	No	Time-to-live in seconds
run_id	string	No	Scope to specific run

Response:

{
  "key": "config/debug",
  "version": 4,
  "expires_at": "2024-01-16T10:30:00Z"
}

---

context_merge

Merge a value with existing data.

Parameters:

Name	Type	Required	Description
key	string	Yes	Key to merge
value	object	Yes	Value to merge
strategy	string	No	replace, merge_shallow, merge_deep, append

Response:

{
  "key": "config/settings",
  "version": 5,
  "merged_keys": ["new_key", "updated_key"]
}

---

context_list

List keys with optional prefix filter.

Parameters:

Name	Type	Required	Description
prefix	string	No	Key prefix filter
run_id	string	No	Scope to specific run
limit	integer	No	Maximum results

Response:

{
  "keys": [
    {
      "key": "config/debug",
      "version": 4,
      "has_ttl": false
    },
    {
      "key": "config/settings",
      "version": 5,
      "has_ttl": true
    }
  ]
}

---

context_history

View version history for a key.

Parameters:

Name	Type	Required	Description
key	string	Yes	Key to inspect
limit	integer	No	Maximum versions

Response:

{
  "key": "config/debug",
  "versions": [
    {
      "version": 4,
      "value": {"enabled": true},
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "version": 3,
      "value": {"enabled": false},
      "updated_at": "2024-01-14T08:00:00Z"
    }
  ]
}

---

Entity Tools

entity_query

Look up an entity by name or alias.

Parameters:

Name	Type	Required	Description
name	string	Yes	Entity name or alias
type	string	No	Filter by entity type

Response:

{
  "entity": {
    "id": "ent_123",
    "name": "Acme Corporation",
    "type": "organization",
    "aliases": ["Acme", "Acme Corp"],
    "description": "Technology company founded in 2010",
    "mention_count": 45,
    "metadata": {}
  }
}

---

entity_search

Semantic search across entities.

Parameters:

Name	Type	Required	Description
query	string	Yes	Search query
type	string	No	Filter by entity type
limit	integer	No	Maximum results

Response:

{
  "results": [
    {
      "id": "ent_456",
      "name": "Jane Smith",
      "type": "person",
      "score": 0.87,
      "description": "Software engineer at Acme"
    }
  ]
}

---

entity_relationships

Get relationships for an entity.

Parameters:

Name	Type	Required	Description
entity_id	string	Yes	Entity ID
direction	string	No	incoming, outgoing, both (default)
type	string	No	Filter by relationship type

Response:

{
  "entity_id": "ent_456",
  "relationships": [
    {
      "id": "rel_001",
      "type": "works_at",
      "direction": "outgoing",
      "target": {
        "id": "ent_123",
        "name": "Acme Corporation",
        "type": "organization"
      }
    }
  ]
}

---

entity_update

Modify entity attributes.

Parameters:

Name	Type	Required	Description
entity_id	string	Yes	Entity ID
name	string	No	Updated name
description	string	No	Updated description
metadata	object	No	Metadata to merge

Response:

{
  "entity_id": "ent_456",
  "updated_fields": ["description", "metadata"]
}

---

entity_merge

Combine duplicate entities.

Parameters:

Name	Type	Required	Description
keep_id	string	Yes	Entity to keep
remove_id	string	Yes	Entity to merge and remove

Response:

{
  "kept_entity_id": "ent_123",
  "removed_entity_id": "ent_789",
  "aliases_merged": 3,
  "relationships_transferred": 5
}

---

entity_list

List entities with filters.

Parameters:

Name	Type	Required	Description
type	string	No	Filter by entity type
sort	string	No	Sort by: name, mention_count, created_at
limit	integer	No	Maximum results
offset	integer	No	Pagination offset

Response:

{
  "entities": [
    {
      "id": "ent_123",
      "name": "Acme Corporation",
      "type": "organization",
      "mention_count": 45
    }
  ],
  "total": 150,
  "has_more": true
}

---

Error Handling

All tools return errors in a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Entity with ID 'ent_999' not found",
    "details": {}
  }
}

Common Error Codes:

Code	Description
not_found	Resource does not exist
invalid_input	Invalid parameter value
namespace_error	Namespace access denied
storage_error	Database operation failed
embedding_error	Embedding generation failed

Tip

MCP clients should handle errors gracefully. Check the error field in responses before processing results.