Meko MCP Server

MCP server and tools reference

The Meko MCP Server provides the primary tools for managing datapacks, conversations, memories, knowledge base, and related search.

To connect from IDEs and MCP-compatible clients, use the Meko MCP URL https://mcp.mekodata.ai/mcp and a user API key from Settings>API Keys. See Universal connectivity and Quick start.

Free tier quotas

On the Free tier, MCP tool calls are metered per account:

Metric Limit (per month) Example tools
Conversations 1,000 conversation_add_message
Retrievals 10,000 context_search, memory_search, knowledgebase_search

When a quota is exceeded, further calls are blocked until you upgrade. Datapack creation and knowledge-base uploads are capped separately. See Meko pricing for the full plan table.

Tools

This page documents 32 Meko MCP tools. Experimental conversation-search tools are hidden unless a deployment explicitly enables them. Project tools, AMP tools, and the four self-learning tools are registered only where a deployment turns them on. Meko Cloud turns on all three. See Manage a project from an agent and Connect to an AMP database.

Authorization comes from the authenticated user and their datapack grants. A deleted datapack is refused. A former member cannot search it or write to it.

Use For
Context search
context_search
Open-ended recall across personal memory, shared knowledge, and past conversations.

Example: What do you know about this project?
Conversation
conversation_*
Full saved chat history and thread replay.

Example: Save or retrieve this chat
Memory
memory_*
Durable facts, preferences, decisions, and useful outcomes you want to recall across agents.

Example: Remember this about me or the project
Knowledge base
knowledgebase_*
Reusable, persistent, indexed shared documents, and collective memories that can be searched across agents.

Example: Search this in the knowledge base
Self-learning
selflearning_*
How well searches matched, and a replay to check a fix. Registered only where the deployment turns self-learning on.

Example: What are this datapack's searches missing?
Datapack
datapack_*
Provisioning and managing Meko workspaces/environments.

Example: Create or manage a workspace
Artifact
artifact_*
Uploading and retrieving files (reports, CSVs, PDFs, code output) for later or cross-agent access.

Example: Save this file for later
Tool Description
context_search Search personal memory, the datapack knowledge base, and the past-conversation cache in parallel.
Use this for open-ended recall when the answer could be in more than one source. Results stay in separate memory, knowledge_base, and conversation buckets so one source doesn't hide another. The conversation bucket can include conversations from every user and agent on the datapack.
Check each bucket's source status before treating an empty result as proof that nothing is stored. Call memory_search or knowledgebase_search directly when you need one source or need to confirm a failed source.
force_source can limit the call to conversation, memory, or knowledge_base; the default auto searches all three.
Daily activity, token savings, and free-tier usage are recorded in the background, so that write does not delay the result.
Each response also carries a match_quality band and a one-line agent_hint.
Typical inputs: query, conversation_id, agent_id, datapack_id, limit, force_source

Conversation tools

Tool Description
conversation_create Create a stored conversation container.
Use this to save a chat/thread, not just a fact or document.
Typical inputs: agent_id, session_id, datapack_id, title, run_id, metadata
conversation_add_message Add a user/assistant turn to a stored conversation. The optional plan is an array of action strings.
Use this to preserve full exchanges; Meko asynchronously extracts durable facts from the saved user turn.
Typical inputs: conversation_id, input, output, agent_id, reasoning, plan, metadata, seed, datapack_id
conversation_get Fetch an agent-owned conversation, optionally with messages.
The supplied agent_id must own the conversation. Use this to review or replay a past conversation.
Typical inputs: conversation_id, agent_id, include_messages, limit, offset, datapack_id
conversation_list List conversations for a datapack across the current user's agent namespaces.
agent_id is used for trace attribution, not result filtering.
Typical inputs: datapack_id, conversation_id, agent_id, limit, offset
conversation_update Update an agent-owned conversation's title or metadata.
Use this when organizing or relabeling stored conversations.
Typical inputs: conversation_id, agent_id, title, metadata, datapack_id
conversation_delete Permanently delete an agent-owned conversation and all its messages.
Use this to remove saved conversation history.
Typical inputs: conversation_id, agent_id, datapack_id
track_token_usage Record a token-usage observation against a conversation trace, so that LLM, embedding, or extraction spend is attributed for free-tier accounting and dashboards.
Use this to pair a billable model call with a recorded usage entry.
Typical inputs: conversation_id, name, input_tokens, output_tokens, total_tokens, model, message_id, datapack_id

Memory tools

Tool Description
memory_add Store durable facts, preferences, decisions, or useful outcomes.
Use this for direct "remember this" requests, facts found only in assistant/tool output, and corrections. Saved conversation turns are extracted automatically.
Typical inputs: text, conversation_id, agent_id, run_id, metadata, messages, datapack_id
memory_search Search the current user's memories across agent namespaces with semantic, keyword, and entity-aware ranking.
Results include memories you promoted, along with your private memories.
Results are ordered by score. raw_similarity_score is the vector store's cosine similarity and does not determine the order by itself.
agent_id is used for trace attribution, not result filtering; don't fan out one search per agent.
limit sets the maximum number of returned results (default: 10). Keep the result set small enough for the model context.
A response with error or an error-shaped detail means the search failed. Only a successful response with an empty results array means no matching memories were found.
Typical inputs: query, conversation_id, agent_id, limit, datapack_id, run_id
memory_get_all List the current user's memories in the specified datapack across agent namespaces, one page at a time, along with the total number of memories and pages.
page defaults to 1. page_size defaults to 20 memories, and is capped at 100. Pages run from the newest memory to the oldest, so a call that omits page returns the newest page, not every memory. To list every memory, request page 1 through total_pages, reading total_pages from each response. Memories added or removed while you page shift rows between pages, so the listing is complete only if none change during it. promoted=true pages through promoted memories instead. An older server rejects page and page_size and returns only the newest rows. Use memory_search to find a specific memory or memory_get_by_id when you know the ID.
agent_id is used for trace attribution, not result filtering.
Typical inputs: conversation_id, agent_id, datapack_id, promoted, page, page_size
memory_get_by_id Retrieve a single memory by ID.
Use this to inspect a memory.
Typical inputs: memory_id, conversation_id, agent_id, datapack_id
memory_update Replace the text of an existing memory.
Use this to correct a remembered fact; agent_id must match the writer.
Typical inputs: memory_id, text, conversation_id, agent_id, datapack_id
memory_delete_by_id Delete one memory.
Use this to remove a specific stored memory; agent_id must match the writer.
Typical inputs: memory_id, conversation_id, agent_id, datapack_id
memory_delete_all Delete every memory that matches the agent, the current user, and the datapack, optionally constrained to one conversation by passing its ID as run_id.
Omitting agent_id targets the meko_agent namespace, not every agent, and omitting datapack_id targets your default datapack. The response returns deleted_count and the scope it used. A large delete can take more than one call: complete: false means memories remain, so call again. delete_incomplete or delete_failed means it stopped early; deleted_count still counts what it removed.
Use this for a full reset or broad cleanup.
Typical inputs: conversation_id, agent_id, run_id, datapack_id
memory_promote Move memories into the datapack's shared knowledge layer, removing them from the user's private store.
Before this one-way action, preview the exact memories, explain team visibility and private-memory removal, and get explicit confirmation. Only datapack owners and maintainers may promote. See Learnings.
Typical inputs: conversation_id, memory_ids, agent_id, datapack_id

Knowledgebase tools

Tool Description
knowledgebase_search Perform hybrid semantic and keyword search over a datapack's knowledge base.
Use this to search uploaded and shared documents.
Typical inputs: query, conversation_id, datapack_id, agent_id, limit
knowledgebase_delete_document Permanently delete one uploaded file and its chunks.
Use this only after the user confirms. The datapack owner, a maintainer, or the file's uploader can delete it. Take document_id from a knowledgebase_search hit. Hits don't include the file name. You can't delete a file until it finishes indexing.
Typical inputs: document_id, conversation_id, datapack_id
knowledgebase_upload_document Request a presigned URL to upload one file to a datapack's knowledge base. Use this when you want the content to be searchable later. To keep a file exactly as-is and get it back whole, use artifact_put instead. Accepts PDF, TXT, TEXT, MD, JSON, CSV, XML, HTML, and HTM; text files must be UTF-8.
The tool doesn't send the file. The agent POSTs it to the returned URL, so it needs the file's bytes and outbound HTTPS access. Send the file's first 3,072 bytes as content_head_base64. Meko checks that sample against the extension before it issues the URL. After the file arrives, Meko checks the stored bytes and indexes them. The agent does not have to confirm the upload.
The URL only accepts a file of exactly size bytes, with SHA-256 content_hash, for 5 minutes. If identical content is already in the datapack, the response is already_uploaded: true and there's nothing to upload.
The per-file size cap depends on your plan: 5 MB on Free, 50 MB on Standard, and 60 MB on Pro. A larger size is refused with VALIDATION_ERROR and no URL. An owner or a maintainer can upload.
Typical inputs: filename, size, content_hash, content_head_base64, conversation_id, datapack_id
knowledgebase_document_status Report the upload and indexing state of a file uploaded with knowledgebase_upload_document.
Poll with the upload response's key as document_key. state is awaiting_upload, indexing, completed, failed, abandoned, or oversized. abandoned means the upload expired, or the stored file was not the type or size that was declared. Read message before you request another URL. oversized means the file is over the cap it was authorized for.
Typical inputs: document_key, conversation_id, datapack_id

Self-learning tools

These tools are registered only where the deployment turns on self-learning, so on other deployments a call fails with tool not found. They need the datapack's owner or a maintainer. selflearning_verify needs a key that can write. The others need a key that can read. They count searches made through context_search. selflearning_status and selflearning_shortfalls default to the portal tab's 14 days, but selflearning_query_log defaults to 7 days. Pass the same last to all three, or you can miss days 8-14 of a to-do. See Self-learning.

Tool Description
selflearning_status Read how well recent searches matched, and the open to-dos.
Start here. Each to-do is one of add_context, clarify_prompts, refresh_sources, or check_source_errors.
Typical inputs: datapack_id, last, conversation_id
selflearning_query_log Read the search log, newest first, 10 a page.
The default band is low. Pass mid, high, or all to widen it. Pass log_id to read one search.
Typical inputs: datapack_id, band, reason, category, log_id, page, last, conversation_id
selflearning_shortfalls List the distinct searches behind one to-do, most repeated first, 10 a page.
Take todo_id from selflearning_status. A search is verified when its latest replay reached a strong match, unverified when it was saved and a memory or document was added after that replay, or open otherwise. It stays open until selflearning_verify has saved it.
Typical inputs: todo_id, datapack_id, page, last, conversation_id
selflearning_verify Replay one weak search and report the match before and after.
Run it after a memory or a document has changed. Pass log_id to save the search as a test prompt and replay it, or test_prompt_id for one already saved. The result has outcome (improved, no_change, worse, or no_baseline), indexing, and nothing_added_since_last_run. A replay counts against your search limit, about 10 a minute on a datapack for each user. replay_timed_out means it may already have run, so don't retry until this search has a new latest_run.
Typical inputs: datapack_id, log_id, test_prompt_id, conversation_id

Datapack tools

Tool Description
datapack_create Provision a new datapack.
Use this to set up a new isolated Meko environment. On Meko Cloud, folder_id files it into a project folder as it is created. A wrong id creates nothing. Omit folder_id and the datapack stays unfiled.
Typical inputs: name, conversation_id, folder_id, datapack_id
datapack_describe Return datapack details and optional status.
Use this to inspect an existing datapack. On Meko Cloud it also returns project, folder, and path. Those are null when the datapack is unfiled.
Typical inputs: datapack_id, include_status, conversation_id
datapack_search Find datapacks visible to the current user, one page at a time.
Use this to find a datapack's ID. It works for accounts of any size. query matches part of the name (case-insensitive), and name matches the exact name. grant limits results to datapacks you own (owner) or that are shared with you (shared). sort is created (newest first, the default) or name.
The response is {datapacks, has_more, next_cursor, total}. While has_more is true, get the next page by repeating the call with the same filters and passing next_cursor as cursor. A Meko API that predates paging returns has_more: true with an empty next_cursor when more rows match; narrow the search with query then. limit sets the page size, 1-100 (default: 20). total is null unless you pass include_total.
Typical inputs: query, name, limit, cursor, grant, sort, include_total, conversation_id
datapack_list List datapacks visible to the current user as one array.
Use this for an account with a small number of datapacks. To find one datapack, use datapack_search.
With no query or limit, it returns every datapack, up to 1,000 by default. Above that, it returns a too_many_datapacks error. With query and no limit, it returns every datapack whose name contains query, and returns too_many_datapacks if more than 100 match. With limit, it returns the first limit matches (at most 100) and doesn't say whether more exist.
Typical inputs: conversation_id, query, limit, datapack_id
datapack_update Update a datapack's name, description, and/or conversation-search opt-out.
At least one of name, description, or conversation_search_opt_out must be provided; clearing a description with an empty string isn't supported. Conversation search is on by default — opting out (restricted to the datapack's owner or a maintainer) is also available from the portal.
Typical inputs: datapack_id, name, description, conversation_search_opt_out, conversation_id
datapack_delete Permanently delete a datapack.
This operation is irreversible and requires an explicit datapack_id.
Typical inputs: datapack_id, conversation_id

Artifact tools

Tool Description
artifact_put Upload a file artifact (report, CSV, PDF, code output, and so on) to a datapack for later retrieval or cross-agent sharing.
Use this when an agent has generated a file it wants to persist. To make a file's content searchable instead, use knowledgebase_upload_document. Uploading the same bytes twice is idempotent and returns the same content hash, which is the lookup key for artifact_get.
Typical inputs: filename, content_base64, content_type, conversation_id, datapack_id, agent_id
artifact_get Retrieve a previously uploaded artifact by its content hash.
Use this when an agent needs to read back a file it, or another agent, previously stored using artifact_put. Files smaller than 1 MB are returned inline; larger files are written to the client's local artifact directory and returned by path.
Typical inputs: content_hash, conversation_id, datapack_id, agent_id

Files under 1 MB are stored inline in the database; files 1 MB and larger are stored in the datapack's object storage and written to a local path on retrieval. Artifacts are content-addressed by SHA-256, so uploads are idempotent. On the Free tier, artifacts are soft-expired 30 days after last access; Standard and Pro have no expiry. Each artifact can be up to 5 MB on every plan; this is separate from the knowledge-base per-file caps above. Expired artifacts are recoverable by re-upload. See Artifacts.