Hosted MCP Endpoint

The hosted MCP endpoint serves the four MemoFS memory tools directly over HTTP — no local server, no checkout, no npx. Point any MCP client that supports the streamable-HTTP transport at your project's URL and the agent speaks the same protocol it would over stdio.

Use it when the machine hosting your agent has no working copy of the repo:

• CI runners and ephemeral build agents
• Cloud-hosted agents (Claude.ai web, server-side Copilot, etc.)
• A teammate's laptop before they've cloned the repo
• Any other cloud-hosted agent or AI app that speaks MCP

If the agent runs on a machine with a full checkout and you want it to benefit from local-first reads, use Hybrid Mode instead.

Quick start

Find your project's exact URL on the dashboard's Memory page. It has the form:

https://memofs.dev/api/v1/projects/<project-id>/mcp

Replace <project-id> with your project's real ID (shown on the dashboard). You'll also need an API key from the API Keys page — pass it as a Bearer token in the Authorization header, exactly as shown in each snippet below.

The hosted endpoint speaks standard MCP streamable-HTTP, so any client that supports that transport works: Coding agents, hosted serverless agents, agents running in CI, and others. Config shapes are mostly interchangeable.

claude mcp add --transport http memofs https://memofs.dev/api/v1/projects/<project-id>/mcp \
  --header "Authorization: Bearer <your-api-key>"

# Run from your project directory, then restart Claude Code.

// Save as `.cursor/mcp.json` in your project (or merge into the global one)
{
  "mcpServers": {
    "memofs": {
      "url": "https://memofs.dev/api/v1/projects/<project-id>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

// Save as `.vscode/mcp.json` in your workspace
{
  "servers": {
    "memofs": {
      "type": "http",
      "url": "https://memofs.dev/api/v1/projects/<project-id>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Authentication

Every request must carry a Bearer Authorization header:

Authorization: Bearer <your-api-key>

The endpoint authenticates with the same salted-hash lookup the rest of the MemoFS Cloud API uses — your API key is the credential, not a bearer token minted by a session. Manage keys on the dashboard's API Keys page.

What's exposed

Only the four memory verbs are wired over this transport — the same tool names and schemas as the stdio server:

Other MCP surfaces from the stdio server — AgentFS session tools (memofs_agent_session_*), graph/raw resources, prompts — are not exposed over HTTP. If an agent calls one, the MCP server returns a validation error (Runtime does not support X). For those features, run the agent on a machine with a checkout and use Hybrid Mode.

Read-only vs. read-write keys

The hosted endpoint enforces key scope at the MCP protocol layer:

A read-only key never rejects context/recall — only the write tools fail, and the failure surfaces as a standard MCP authorization error, not an HTTP 403.

Write attribution

Writes are stamped with the API key's label as the writer field. Clients can't forge this — the tool call schema has no writer parameter, so the server derives it solely from the authenticated key. Each successful write is also logged as a memory_events row visible on the dashboard's Memory page.

Local pickup of cloud writes

Writes land in the project's hosted replica. A local checkout only picks them up when it runs memofs cloud sync pull — pulls are always explicit, the same as with Hybrid Mode. The hosted endpoint does not push writes back to any machine's local .memofs/ directory automatically.

Rate limits

Rate limits are tiered per API key:

Exceeding the limit returns HTTP 429 with a Retry-After indicating when the bucket resets. The MCP client surfaces that as a transport error; most agents retry transparently.

Troubleshooting

402 "The hosted MCP endpoint requires a Pro or Teams plan."

Your API key belongs to a Free account. Upgrade from the dashboard's Billing page, or use a key minted under a paid account.

404 "Project not found. Push it with memofs cloud sync push first."

The project has never been synced to the cloud, so there's no replica to serve. Clone the repo on a machine with the CLI, then run memofs cloud sync push once to provision the hosted replica.

403 "Forbidden"

The authenticating key's account doesn't own the project. Re-check that you copied the right <project-id> and that the key belongs to the same account (or team) that owns the project.

Write tools return an MCP authorization error

Your key is read-only. Either mint a read-write key on the API Keys page, or rely on memofs.context / memofs.recall only.

429 "MCP rate limit exceeded. Try again shortly."

You hit the plan's per-minute cap. Back off briefly; the Retry-After header tells you when the bucket resets. For higher throughput, upgrade to Teams (300 req/min) or split work across multiple agents with their own keys.

Hosted agent can't reach memofs://... resources or memofs_agent_session_* tools

Those surfaces are stdio-only — the hosted endpoint exposes just the four memory verbs by design. Use Hybrid Mode on a machine with a checkout to reach the full surface.

See Also

• Local Mode — the full tool/flag surface for the stdio server.
• Hybrid Mode — local stdio server that mirrors writes to the cloud replica.
• CLI memory commands — memofs cloud sync push to provision a project's hosted replica; memofs cloud sync pull to reconcile local memory with cloud writes.