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 full AI turn loop — memory retrieval, context packing, tool use, memory formation. The response includes how many memories were formed during the turn.

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

motebit_remember

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

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

motebit_recall

Searches the motebit's memory graph by semantic similarity. Results are privacy-filtered — high-sensitivity memories are excluded from external responses.

{ "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 all tools from the motebit's tool registry — built-in tools and connected MCP server tools. 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. If no authToken is configured, all endpoints are open.

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.