MCP Server Mode

MCP server mode turns the motebit inside-out. Instead of the motebit calling external tools via MCP, other agents connect to the motebit as an MCP server, discover its capabilities, and submit requests. The motebit responds with identity-tagged, policy-gated results — and for autonomous tasks, cryptographically signed execution receipts.

This is the sovereign agentic surface. A dumb tool proxy can expose functions. Only a motebit can prove who executed the task, remember across sessions, and enforce governance at the boundary.

Starting the server

Stdio transport (for MCP host integration)

motebit serve

HTTP transport (for remote agents)

motebit serve --serve-transport http --serve-port 3100

With an identity file:

motebit serve \
  --serve-transport http \
  --identity motebit.md

Direct mode (no LLM)

For service agents that expose tools without an AI loop — bypasses the LLM entirely and maps the incoming prompt directly to the tool's first required string parameter. Combined with --tools to load external tool definitions:

motebit serve \
  --serve-transport http \
  --identity motebit.md \
  --tools ./dist/tools.js \
  --direct \
  --self-test

The --self-test flag submits a task to itself via the relay after registration, proving the full loop works (submit → route → execute → receipt → settle). The npm create motebit -- --agent scaffold includes --self-test in the production start script (not dev, since the relay can't reach localhost).

Adding AI reasoning

The scaffold starts in direct mode. To enable LLM-powered tool selection and multi-tool workflows, remove --direct from your start command and set an API key:

# Set your provider key (Anthropic by default, Ollama for local)
ANTHROPIC_API_KEY=sk-ant-...

# In package.json scripts
"start": "npx motebit serve --identity ./motebit.md --tools ./dist/tools.js --serve-transport http"

The AI loop picks which tool to use, can chain multiple tools per task, and reasons about the prompt before execution. Same identity, same signed receipts, same trust accumulation. The intelligence is pluggable — direct mode and AI mode are two points on the same spectrum.

Auth tokens are configured via the config file (authToken field), not via CLI flag.

Synthetic tools

Six tools are registered automatically when the server starts. Four are conditional — they only appear when the runtime provides their backend (which the CLI always does).

motebit_query

Sends a message through the AI turn loop: context packing, tool use and memory formation. Whose turn it is depends on who is asking, the same rule motebit_recall follows. Over stdio, from the MCP host you launch on your own machine, the query is yours: it runs as an owner turn with your memories and context, and memories_formed is the number of memories the turn formed. Over HTTP the caller is another principal, whatever credential it presents. Then the turn recalls none of the owner's memories and receives none of the owner's private context: no trust graph, self-model, installed skills, recent events or live session facts. It sees the motebit's identity and persona, the tools a caller may use, and the model it runs on. Memories the turn forms are marked as coming from a peer agent, and memories_formed is always 0.

{ "message": "What do you know about the deployment pipeline?" }

motebit_remember

Stores a memory in the motebit's semantic graph. External callers may store only "none" sensitivity — attempts to store "personal", "medical", "financial", or "secret" memories are denied (fail-closed).

{ "content": "The deploy key rotates every 90 days", "sensitivity": "none" }

motebit_recall

Searches the motebit's memory graph by semantic similarity. The owner's memories are served only to the owner, and the owner is the local stdio session: the MCP host you launched on your own machine. HTTP callers are never the owner, whatever they present. That includes another motebit, the relay, a static or pluggable bearer token, and even a token signed under this motebit's own key. Your motebit signs those for the workers it hires and the servers it connects to, so they could be replayed. Every HTTP caller is refused with no memory content. Nothing that worked before is lost: motebit serve never resolved its own key for HTTP callers, so reading your memories over HTTP was not reachable anyway. Read your memories over stdio. For the owner, medical, financial and secret memories are still excluded.

Never bridge stdio to a network. stdio counts as the owner by construction, because only a process you launched can reach the pipe. Wrapping a stdio motebit serve in an mcp-remote- or supergateway-style bridge that exposes it over HTTP or SSE makes every remote caller of the bridge the owner, and serves them your memories and live state. Use HTTP transport for other agents; it never treats a caller as the owner.

{ "query": "deployment credentials", "limit": 5 }

Each result includes:

motebit_task

The differentiator. Submits a prompt for autonomous execution. The motebit runs the full agentic loop (potentially multiple tool calls), then signs the result as an ExecutionReceipt with its Ed25519 private key. The receipt includes:

• Task ID, timestamps, status
• SHA-256 hashes of the prompt and result
• Tools used, memories formed
• Ed25519 signature

Any agent receiving the receipt can verify it was executed by this specific motebit using @motebit/crypto.

{ "prompt": "Check the API health endpoint and summarize the response" }

motebit_identity

Returns the motebit's identity. If the server was started with --identity motebit.md, returns the full signed identity file. Otherwise returns a JSON summary with the motebit ID, public key, and W3C did:key.

motebit_tools

Lists all tools available to the motebit (built-in + MCP), including their risk levels. Useful for capability discovery before submitting tasks.

Proxied tools

In addition to the six synthetic tools, the server exposes the motebit's served tools from its tool registry. Tools marked localOnly are never served. Those are the tools that act for the owner: the filesystem, shell, memory, and every tool from an MCP server the owner connected (settings, /mcp add, or mcp_servers in config). Tools loaded with motebit serve --tools are served unless their definition says localOnly. Every proxied tool call passes through the policy gate:

• Allowed — executes and returns the result with an identity tag
• Denied — returns a policy denial message
• Requires approval — returns a governance message (the motebit owner must approve)

Resources and prompts

The server also exposes MCP resources and prompts:

HTTP bearer auth

When authToken is configured, all HTTP endpoints except /health require a bearer token:

Authorization: Bearer my-secret-token

• /health — always public (returns { status: "ok", motebit_id: "..." })
• POST /mcp — requires auth (StreamableHTTP transport, uses Mcp-Session-Id header for session management)

Requests with a missing or incorrect token receive a 401 Unauthorized response. HTTP transport is fail-closed: if no authToken is configured, every request except /health is still rejected with 401 unless the caller presents a motebit signed token (Authorization: Bearer motebit:<signed-token>). Open access is never a default.

A motebit signed token is accepted only when its audience is mcp:call, its sub is this server's motebit_id (the token is bound to its target), its signature and expiry hold, and its jti has not been used before. Callers mint a fresh token for every HTTP request; @motebit/mcp-client does this for you. A refused token gets 401 {"error":"invalid motebit token","reason":"..."}. The relay authenticates on a forwarded task with its own mcp:call token, bound to this server and signed by the relay key; a server with relayTrust verifies it against the pinned relay key and serves the caller as its relay. A task:dispatch token is never accepted as the bearer: it is an admission record passed only as the motebit_task dispatch_token argument, and a submitter may hold one too (#981).

Identity tagging

Every result — from synthetic tools and proxied tools alike — is tagged with the motebit's identity:

[result content]
[motebit:a1b2c3d4 key:0123456789abcdef]

This allows any consumer to trace which motebit produced which result, even without full receipt verification.