> For the complete documentation index, see [llms.txt](https://vayl.gitbook.io/vayl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vayl.gitbook.io/vayl-docs/documentation/mcp-tools.md).

# MCP tools

Vayl's API **is** its set of MCP tools — there's no REST layer to learn. Any MCP client connects and calls them; usually the **LLM in your agent** calls them automatically, but you can also call them from your own code. See [Calling Vayl from code](/vayl-docs/documentation/getting-started/calling-vayl-from-code.md).

## Reading these pages

Each tool page lists the tool's parameters; optional ones have a default or are marked `?`. Over MCP you pass arguments as a JSON object:

```json
{"name": "remember", "arguments": {"text": "We use Postgres", "user_id": "proj_7"}}
```

For the exact, always-current schema of every tool, call `tools/list` from any MCP client.

## Conventions

* **Scoping.** Every tool accepts optional `user_id`, `agent_id`, and `run_id` to target a [memory space](/vayl-docs/documentation/core-concepts/memory-spaces.md). Leave them blank for a single space.
* **Safety annotations.** Each tool carries MCP annotations, so clients can auto-run reads and confirm before an irreversible erasure.
* **Capabilities.** On `vayl-server`, every tool checks the capability its caller's role grants, and is fail-closed.

## Groups

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-database" style="color:$primary;">:database:</i> Memory</h4></td><td>Store, query, correct, and time-travel over facts.</td><td><a href="/pages/atmh20zKFo3dWE6nALWX">/pages/atmh20zKFo3dWE6nALWX</a></td></tr><tr><td><h4><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i> Safety and gating</h4></td><td>Gate irreversible actions and require approval.</td><td><a href="/pages/FXBBWNQcHGSp5V9G057o">/pages/FXBBWNQcHGSp5V9G057o</a></td></tr><tr><td><h4><i class="fa-file-signature" style="color:$primary;">:file-signature:</i> Accountability</h4></td><td>Signed, tamper-evident record of what the agent did.</td><td><a href="/pages/R2NPTpA8ljGHbWMvp6xn">/pages/R2NPTpA8ljGHbWMvp6xn</a></td></tr><tr><td><h4><i class="fa-scale-balanced" style="color:$primary;">:scale-balanced:</i> Compliance (GDPR)</h4></td><td>Erasure, export, and retention with signed receipts.</td><td><a href="/pages/yBNIgVqSfcovyrB5U6PP">/pages/yBNIgVqSfcovyrB5U6PP</a></td></tr><tr><td><h4><i class="fa-user-gear" style="color:$primary;">:user-gear:</i> Administration</h4></td><td>Principals, policy, and operations.</td><td><a href="/pages/KWshiOyBWcyDM5AHxYMU">/pages/KWshiOyBWcyDM5AHxYMU</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vayl.gitbook.io/vayl-docs/documentation/mcp-tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.