Skip to content

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.

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.

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:

Terminal window
curl -s https://app.membase.com/plugin/openapi/agent-protocol.json -o agent-protocol.json
npx openapi-typescript agent-protocol.json -o membase.d.ts

Three 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).

  • 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=true changes nothing and answers 428 confirmation_required with a how sentence; relay it and stop.
  • Treat 403 as 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.