---
title: "Meko MCP Server"
url: "https://docs.mekodata.ai/reference/mcp-server/"
---

# 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 [Integrations](/integrations/) and [Quick start](/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](https://mekodata.ai/pricing/) for the full plan table.

## Tools

This page documents 28 Meko MCP tools. Experimental conversation-search tools are hidden unless a deployment explicitly enables them.

Authorization comes from the authenticated user and their datapack grants.

Breaking change in v2.1.0

Tool-level `scope` arguments (`"read"`, `"write"`, `"admin"`) were retired. Don't send them on MCP tool calls. New clients no longer see `scope` in tool schemas. A temporary compatibility shim currently strips the obsolete argument from older clients and will be removed in a future release. Rerun the installer or install the current plugin from [`yugabyte/meko-skills`](https://github.com/yugabyte/meko-skills) so hooks and skills stop sending it. Installer flags such as `--scope user|project` are unrelated and remain supported.

Use For 

[Context search](#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-tools)  
`conversation_*` Full saved chat history and thread replay.

Example: *Save or retrieve this chat* 

[Memory](#memory-tools)  
`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-tools)  
`knowledgebase_*` Reusable, persistent, indexed shared documents, and collective memories that can be searched across agents.

Example: *Search this in the knowledge base* 

[Datapack](#datapack-tools)  
`datapack_*` Provisioning and managing Meko workspaces/environments.

Example: *Create or manage a workspace* 

[Artifact](#artifact-tools)  
`artifact_*` Uploading and retrieving files (reports, CSVs, PDFs, code output) for later or cross-agent access.

Example: *Save this file for later*

### Context search

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.  
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` Return a recent window of roughly 20 memories plus the total count across the current user's agent namespaces.  
This is not a complete list or export and doesn't accept pagination arguments. Use `memory_search` for older memories 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` 

`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 memories for an agent, optionally narrowed by run ID.  
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](/architecture/core-concepts/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`

### Datapack tools

Tool Description 

`datapack_create` Provision a new datapack.  
Use this to set up a new isolated Meko environment.  
Typical inputs: `name, conversation_id, datapack_id` 

`datapack_describe` Return datapack details and optional status.  
Use this to inspect an existing datapack.  
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 [Work with artifacts](/guides/working-with-artifacts/).