MCP frameworks
An agent framework with an MCP client needs no Membase-specific code: the server URL and the key as a header, and it discovers the tools. Without a framework, the OpenAPI document generates TypeScript types or a client for another language.
Give the framework the server
Section titled “Give the framework the server”A framework with an MCP client (LangChain’s MCP adapters, the OpenAI Agents SDK, Pydantic AI, Mastra, and most others) needs no Membase-specific code. Give it the server as a Streamable HTTP endpoint with the key in the header:
{ "url": "https://api.app.membase.com/mcp-http", "headers": { "Authorization": "Bearer mbk_…" } }It discovers the key’s tools with tools/list and calls them by the names in the
API Reference: the same operations, arguments and answers as
REST, and no tool takes a Memory. Where the framework’s own MCP client speaks OAuth, leave
the header out and the user consents in the browser instead; the connection is then
read-only, which is what a user-facing agent usually wants.
A user-facing agent whose end users each hold their own Membase account connects by consent instead, one account at a time; Multi-user isolation has the patterns.
Without an SDK
Section titled “Without an SDK”Any HTTP client works. The OpenAPI document generates TypeScript types, or a client for
another language with OpenAPI Generator. It types the request bodies only: every response is
an untyped JSON object, and it names no server or auth scheme, so set the base URL
(https://api.app.membase.com) and the Authorization: Bearer header by hand:
curl -s https://app.membase.com/plugin/openapi/agent-protocol.json -o agent-protocol.jsonnpx openapi-typescript agent-protocol.json -o membase.d.tsThree requests cover most integrations: GET /v1/profile-facts, POST /v1/search with {"q": …}
and POST /v1/memories/add with {"content": …}, each with the bearer header. No request names a
Memory: a search answers {items, partial} across every Memory the key reaches, each passage
naming its memory_name, and a write lands in the key’s write target (a key that reaches
several text Memories is refused with 422 write_target_required).
Rules that hold in every shape
Section titled “Rules that hold in every shape”- Profile once, search per question. The profile facts are few and standing; search is a turn inside the user’s memory.
- Cite the Memory. Every hit names the Memory it came from (
memory_name, over REST, MCP and the SDKs alike); say where an answer came from. - Save what the user supplied, in their words, and only when they asked or plainly meant to.
- Never confirm on your own. On a Full access key, a delete or forget without
confirm=truechanges nothing and answers428 confirmation_requiredwith ahowsentence; relay it and stop. - Treat
403as withdrawn access. The owner narrowed or revoked the key; do not retry with it. - Expect the first search to be slow. Up to a minute after a quiet spell; keep the SDK’s timeout.
The same rules, with the reasons, are on Memory operations.