MCP Tools Reference
Complete reference for all tools available through the Yanai MCP server. Yanai exposes just 2 tools — designed to minimize agent decision overhead and context token cost while giving AI agents full access to your memory.
Connection
Server URL: https://mcp.yanai.ai
Authentication: OAuth 2.1 + PKCE (initiated automatically by MCP clients)
OAuth Discovery: https://mcp.yanai.ai/.well-known/oauth-authorization-server
Session Scope
Every MCP session is scoped to either personal, organization, or role data. The scope is chosen during OAuth authorization and enforced on all tool calls.
- Personal scope — Access to personal aspects and memories only. No team or org data.
- Organization scope — Access to org-owned aspects, team memories, and org memory only. No personal data.
- Role scope — A specialization of org scope. Can read all aspects belonging to the same user within the org, but can only write to the role's own aspect.
search_context
Unified search across ALL memory layers — user aspects, teams, and organization. Returns ranked results with relevance scores, plus context metadata (user profile, aspects, teams, role info).
This is the primary retrieval tool. Call it at the start of every conversation and whenever you need to recall knowledge. It replaces the need for separate profile, aspect listing, summary, and fact-querying tools — everything comes back in one call.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The search query — be specific and topical for best results |
sectors | string[] | No | Filter by cognitive sectors: episodic, semantic, procedural, emotional, reflective |
Returns:
An object containing:
results— Array of matching memories with relevance scores, sorted by relevancecontext— Metadata object with:user— User profile (name, email)aspects— All aspects visible in the current scope (with IDs, names, descriptions)teams— Teams the user belongs to (org/role scope only)role— Role identity info (role scope only, includesis_own_roleflag)
When to use:
- At the start of every conversation — the context metadata gives you the user's profile, aspects, and teams in a single call
- Whenever you need to recall existing knowledge about a topic
- Search multiple times with different queries for comprehensive context
Scope behavior:
- Personal scope — Searches personal aspects only
- Organization scope — Searches org-owned aspects, team memories, and org-level memory
- Role scope — Searches all user aspects in the org (cross-role), with the role's own memories prioritized. Also searches team and org entries.
Relevant search results are automatically reinforced — no separate reinforcement call is needed.
store_memory
Store memories with automatic aspect classification, key generation, and multi-aspect routing. Supports individual memories and bulk extraction from conversation summaries.
This is the primary storage tool. It handles all knowledge capture — from quick single-fact storage to end-of-conversation bulk extraction.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
content | string | Yes | The content to store (single memory) or conversation summary to extract from (extract mode) |
mode | string | No | auto (default), single, or extract. See modes below. |
aspect_id | string (UUID) | No | Target aspect. If omitted, auto-classifies to the best matching aspect(s). |
key | string | No | Descriptive title. If omitted, auto-generated from content. |
tags | string[] | No | Keywords for searchability |
Modes:
| Mode | Behavior |
|---|---|
auto | Default. Picks single or extract based on content length. Short content → single memory. Long content → bulk extraction. |
single | Stores one memory. Auto-classifies to 1-3 relevant aspects if aspect_id is omitted. |
extract | Treats content as a conversation summary. Extracts multiple discrete memories and stores each to the appropriate aspect. |
Returns:
For single mode: The created memory entry with its ID, auto-generated key, assigned aspect, and cognitive sector.
For extract mode: Count and details of all extracted and stored memories.
When to use:
- During conversations — Store individual facts, decisions, preferences, and insights as they come up. Just pass
contentand let the server handle classification. - At the end of conversations — Use
mode: "extract"with a summary to capture anything not stored individually. - For structured facts — Include relevant details in the content (e.g., "Project Alpha uses Next.js as of March 2026") and the system will capture the temporal relationship.
Scope behavior:
- Personal scope — Stores to personal aspects only
- Organization scope — Stores to org-owned aspects only
- Role scope — Can only write to the role's own aspect. The server enforces this — just pass content and it will be stored in the right place.
Tips:
- Prefer many small, specific memories over fewer large ones
- Each memory should capture one discrete fact or decision
- Don't ask the user "should I save this?" — store proactively
- Omitting
aspect_idandkeyis fine — the server auto-classifies and auto-generates both
Rate Limits
The MCP server enforces per-user rate limits:
| Operation | Limit |
|---|---|
search_context | 30 requests/minute |
store_memory | 30 requests/minute |
Rate limits are per-user, not per-session. Multiple connected tools share the same limit.
Design Philosophy
Yanai's MCP surface is intentionally minimal. Two tools instead of twelve means:
- Less agent confusion — AI agents spend fewer tokens deciding which tool to use
- Lower context cost — Tool descriptions consume less of the agent's context window
- Faster adoption — New integrations are trivial to build against
- Your context stays portable — A simple API surface means less lock-in to any specific integration pattern