Space Context

[Space Context]

Space Context MCP server

[License: MIT] [MCP] [OAuth 2.1] [Cloudflare Workers] [Docs]

A remote MCP server that gives Claude, ChatGPT, Codex, Cursor, VS Code or any MCP client access to your Space Context spaces. The assistant can list spaces, search them, read them by section or as one page, ask them questions, compare scans and show the photo evidence. Every item, issue and key location says whether a second, independent check found it on its own photo (verified, unconfirmed or from the narration), so the assistant knows what to state and what to hedge. If you allow it, it can also scan spaces for you.

https://mcp.spacecontext.app/mcp

It speaks MCP over Streamable HTTP and authorizes with OAuth 2.1 (dynamic client registration and client ID metadata documents). It's stateless (createMcpHandler from agents, MCP SDK v2) behind @cloudflare/workers-oauth-provider. This package isn't published to npm. Use the hosted server above, or deploy your own.

Connect an assistant

You never paste a key. Connecting works like this:

1. Your assistant opens a Space Context page. You sign in with Apple, Google or a code sent to your email, using the same account as the iPhone app.
2. You choose whether the assistant may see sensitive values (Wi-Fi passwords, door and alarm codes, the narration) and whether it may scan spaces for you. By default it can do neither. Scanning needs a card on file in your account (added in the console, nothing charged): without one, the page offers to connect read-only instead, or to try again once the card is added.
3. The server creates an API key for this connection only, listed as MCP · <assistant> in the console. Its scopes are spaces:read and scans:read, plus spaces:sensitive and scans:write if you ticked them.

Revoking that key in the console ends the connection, and the assistant asks you to sign in again. Connecting the same assistant again replaces its previous key. The assistant sees your live spaces, including the ones scanned with the iPhone app. A space from the app becomes readable once it has been screened for sensitive values: the first read starts the screening, which takes a minute or two. Full guide: Connect an assistant.

Tools

Reading tools, on every connection (annotated read-only and idempotent):

These tools work only on a connection where the user ticked let it scan spaces. On any other connection the API refuses them with INSUFFICIENT_SCOPE:

Resources: spacecontext://spaces (the list, JSON) and spacecontext://spaces/{space_id} (a space as Markdown). Prompts: check_out_report (compare two scans and write a report that keeps confirmed changes apart from what may be missing) and where_is (find one thing, with its area and evidence photo).

No tool reaches the open web. Space content is returned as data, never as instructions: the server's instructions say so, and so does a note in every result that carries space content. The server card at /.well-known/mcp/server-card.json lists tools, resources and prompts before sign-in. Arguments and results: MCP tools.

Deploy your own

The server is a Cloudflare Worker that talks to a Space Context API (…/v1, with API_V1_ENABLED = "true"). It signs people in through the API's own sign-in endpoints and creates one API key per connection. Everything it keeps is in KV: OAuth clients, grants and tokens (grants carry the connection's API key and are encrypted by the OAuth library), and sign-ins in progress, for ten minutes, encrypted with a key that only the user's browser holds.

1. Install and build the SDK (the server imports it), from the repository root:

npm installnpm run build -w @spacecontext/sdk

2. Create the KV namespace for OAuth clients, grants and tokens, and put its id in kv_namespaces in wrangler.jsonc. This and the next steps run in packages/mcp:

cd packages/mcpnpx wrangler kv namespace create OAUTH_KV

3. Set the configuration in wrangler.jsonc (name, the custom domain in routes, and vars):

4. Add the secret for Google sign-in:

npx wrangler secret put GOOGLE_WEB_CLIENT_SECRET

5. Register the callback URLs with the providers:

• Google: add ${PUBLIC_URL}/authorize/google/callback as an authorized redirect URI of the web OAuth client.
• Apple: add ${PUBLIC_URL}/authorize/apple/callback as a return URL of the Services ID.

Without both GOOGLE_WEB_CLIENT_ID and the secret, the Google button isn't shown, and the same goes for Apple without APPLE_SERVICES_ID. Email sign-in is always offered. The API checks Google and Apple tokens against its own web client ID and Services ID, so use the same ones the API is configured with.

6. Deploy:

npm run deploy     # wrangler deploy of the top-level environment

Keep these settings from wrangler.jsonc:

• global_fetch_strictly_public stays on. The server fetches client metadata documents from URLs that clients choose, so a plain fetch must never reach private addresses. The API is reached through the BACKEND binding.
• With workers_dev and preview_urls off, the server answers only on its custom domain.
• ratelimits limit each client IP to 10 registrations (/register) and 60 sign-in page requests (/authorize…) a minute, answered with 429 and Retry-After: 60 beyond. Rate limits aren't inherited by environments, and each namespace_id must be unique in your Cloudflare account. Without the bindings (as in dev) nothing is limited.
• Access tokens last one hour. A grant lives for 90 days after its last refresh. A client registered dynamically is deleted after 180 days without a token request.

wrangler.jsonc also defines dev (local, see below) and staging (Space Context's own staging deployment).

Develop

npm run dev -w @spacecontext/mcp     # http://localhost:8788, against an API on 127.0.0.1:8787npm test -w @spacecontext/mcp        # the full OAuth flow and MCP calls in workerd, against a fake API

The API isn't part of this repository. The tests don't need it: they drive registration, PKCE, consent, token and real MCP calls against a fake API. The dev environment sets no Google or Apple client, so local sign-in uses the emailed code. Read CONTRIBUTING.md before adding a tool: any tool that writes or spends must sit behind scans:write and be annotated honestly.

MIT © Finikos S.r.l.