cortex/docs/mcp-tools.md

MCP Tools

Cortex exposes MCP tools over:

http://localhost:5117/mcp

The isolated test endpoint is:

http://localhost:5217/mcp

CreateProject

Creates a project. Projects are explicit and must exist before items can be added.

Arguments:

Name	Type	Required	Description
name	string	yes	Human-readable project name.

ListProjects

Lists projects.

Arguments: none.

AddRequirement

Adds a requirement, decision, or constraint.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
statement	string	yes	Requirement, decision, or constraint statement.
context	string	yes	Context explaining why it matters.
tags	string array	no	Optional tags.
status	string	no	Optional status. Defaults to active.

AddLocation

Adds where a concrete thing is located.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
itemName	string	yes	Object, file, or resource being located.
place	string	yes	Place where the item is located.
details	string	no	Extra location details.
tags	string array	no	Optional tags.
status	string	no	Optional status. Defaults to active.

Example:

{
  "project": "home",
  "itemName": "USB-C charging brick",
  "place": "blue backpack",
  "tags": ["charging", "backpack"]
}

AddTodo

Adds an action item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
task	string	yes	Action to complete.
priority	string	yes	Priority such as low, normal, high, or urgent.
dueAt	timestamp	no	Optional due timestamp.
details	string	no	Extra task details.
tags	string array	no	Optional tags.
status	string	no	Optional status. Defaults to active.

AddNote

Adds a general note or idea.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
subject	string	yes	Note subject.
body	string	yes	Note body.
tags	string array	no	Optional tags.
status	string	no	Optional status. Defaults to active.

FindItems

Finds memories with hybrid search.

Name	Type	Required	Description
queries	string array	yes	One to four natural-language search queries. Each query is embedded and searched separately.
project	string	required unless global	Project name or slug.
searchAllProjects	boolean	no	Set true for global search.
category	string	no	Optional category filter: requirement, location, todo, or note.
limit	integer	no	Result limit from 1 to 50. Defaults to 10.

Results are distinct items. If an item has multiple embeddings, Cortex returns the best matching embedding/query pair with matchedQueryIndex, matchedEmbeddingPosition, and matchedEmbeddingLabel.

ListItemEmbeddings

Lists the default and additional embeddings for an item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
itemId	GUID	yes	Item id from a previous result.

AddItemEmbedding

Adds an additional discoverability embedding. This does not change the item's canonical title/content.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
itemId	GUID	yes	Item id from a previous result.
text	string	yes	Aspect-specific text to embed.
label	string	no	Short label for what the embedding targets.

UpdateItemEmbedding

Updates an additional embedding. The generated default embedding at position 0 cannot be edited directly.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
itemId	GUID	yes	Item id from a previous result.
embeddingId	GUID	yes	Embedding id from ListItemEmbeddings.
label	string	no	Replacement label. Pass an empty string to clear.
text	string	no	Replacement embedding text.

DeleteItemEmbedding

Deletes an additional embedding. The default embedding at position 0 cannot be deleted.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
itemId	GUID	yes	Item id from a previous result.
embeddingId	GUID	yes	Embedding id from ListItemEmbeddings.

UpdateRequirement

Updates an existing requirement item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
id	GUID	yes	Item id from a previous result.
statement	string	no	Replacement statement.
context	string	no	Replacement context.
tags	string array	no	Replacement tag list.
status	string	no	Replacement status.

UpdateLocation

Updates an existing location item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
id	GUID	yes	Item id from a previous result.
itemName	string	no	Replacement item name.
place	string	no	Replacement place.
details	string	no	Replacement details. Pass an empty string to clear.
tags	string array	no	Replacement tag list.
status	string	no	Replacement status.

UpdateTodo

Updates an existing todo item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
id	GUID	yes	Item id from a previous result.
task	string	no	Replacement task.
priority	string	no	Replacement priority.
dueAt	timestamp	no	Replacement due timestamp.
clearDueAt	boolean	no	Set true to clear the due timestamp.
details	string	no	Replacement details. Pass an empty string to clear.
tags	string array	no	Replacement tag list.
status	string	no	Replacement status.

UpdateNote

Updates an existing note item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
id	GUID	yes	Item id from a previous result.
subject	string	no	Replacement subject.
body	string	no	Replacement body.
tags	string array	no	Replacement tag list.
status	string	no	Replacement status.

DeleteItem

Soft-deletes an item.

Name	Type	Required	Description
project	string	yes	Existing project name or slug.
id	GUID	yes	Item id.

Deleted items are excluded from search.