# MCP Reference

> The model-context-protocol tools Lobu exposes for reading and writing shared organizational context.

Lobu exposes a Model Context Protocol (MCP) endpoint. Agents (ChatGPT, Claude, OpenClaw, and your own) use these tools to read and write the same permission-aware, org-scoped context. Wire it up from [Connect from ChatGPT](/connect-from/chatgpt/), [Claude](/connect-from/claude/), or [OpenClaw](/connect-from/openclaw/).

- **Public:** `https://lobu.ai/mcp` (self-hosted: `http://localhost:8787/mcp`)
- **Org-scoped:** `{user_url}/mcp/{org}` — pin the org in the URL path (e.g. `https://lobu.ai/mcp/acme`) to scope every call to that org. Otherwise callers pick an org at sign-in.

Auth reuses the shared session; `lobu memory run <tool> '{...}'` invokes the same tools from the [CLI](/reference/cli#memory).

## Agent tools (`tools/list`)

These ship on MCP `tools/list` and are what an agent discovers automatically.

| Tool | Purpose | Kind |
| ---- | ------- | ---- |
| `search_memory` | Semantic search of saved workspace memory: entities, facts, decisions, preferences, observations, notes. *"What do we know?"* | read |
| `save_memory` | Append facts/preferences/decisions/observations to memory. Pass `supersedes_event_id` to replace a fact; `entity_ids` to attach to entities. | write |
| `search_sdk` | Discover ClientSDK methods and runtime helpers by name/namespace. Returns signatures + access requirements; `mode="read"` filters to read-only. | read |
| `query_sdk` | Read data through typed SDK methods (entities, relationships, feeds, operations, metrics). Scripts are TS; `await ctx.sleep(ms)` for polling. | read |
| `query_sql` | Paginated, sortable, member-safe read-only SQL. Tables auto-scope to the bound org; virtual feeds are live-only. | read |
| `run_sdk` | Any mutating workspace action (CRUD entities, connections, Behaviors, feeds, operations, templates). `dry_run:true` previews without executing. | write |

Power rule: discover with `search_sdk` → read with `query_sdk`/`query_sql`/`search_memory` → write with `run_sdk`/`save_memory`.

## Sandboxing

`query_sdk` and `run_sdk` scripts run in an isolated V8 isolate (`isolated-vm`), not in the agent's process or the gateway. The TypeScript source is compiled with esbuild, executed inside the isolate, and every SDK call is bridged back to the host where it is permission-gated and org-scoped. Caps: **1 MB of output, 200 SDK calls per script, 180 s wall-clock max, 30 s per `ctx.sleep()`**. A script that exceeds a cap fails with a clear error instead of hanging. `run_sdk` with `dry_run:true` validates the method path and access tier, executes read calls so the script can inspect state, and returns the writes it would have made in `side_effect_preview` without dispatching them.

Reactions (behavior post-processing) run through the same isolate runner — see [Author a connector](/getting-started/author-a-connector/#reactions).

## What an agent is told to do

Keep calls short and never fabricate a returned URL or identifier. Read a task or a memory search before answering, and save what you observe so it is shared with your other agents. Every write is permission-gated by the caller's org role and `mcp:*` scope (`read` / `read,write`).

## Admin surface (not on `tools/list`)

First-party / admin tools (`manage_agents`, `manage_connections`, `manage_feeds`, `manage_operations`, `manage_behaviors`, `query_metric`, `list_metrics`, `list_organizations`, and friends) are NOT advertised on MCP `tools/list`. Agents and controllers reach the same surface through `query_sdk`/`run_sdk` ClientSDK namespaces, and admin UI / REST consumers dispatch them at `POST /api/:org/:toolName` (see [REST API](/reference/api-reference/)).

## Related

- CLI: [CLI Reference](/reference/cli/) — `lobu memory run` runs these same tools
- Proxy: [MCP proxy guide](/guides/mcp-proxy/)
- Memory: [Memory](/getting-started/memory/)