Space Context MCP server
Commit Oct 28, 2026Allows AI assistants to access, search, and analyze filmed physical spaces, including comparing scans and viewing photo evidence.
Also known as finikoslab/spacecontext, spacecontext
- Stars
- 0
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- 0.2.1
- Last commit
- Oct 28, 2026
- License
- MIT
What is Space Context MCP?
Space Context allows AI assistants to access, search, and analyze filmed physical spaces, including comparing scans and viewing photo evidence. It exposes 13 tools, such as list_spaces, search_spaces, get_space.
Summary generated from the project's README
About Space Context MCP server
Analyzing filmed physical environments through an AI assistant is what Space Context enables. This remote MCP server connects clients like Claude, ChatGPT, Cursor, and VS Code to your recorded spaces, allowing an assistant to list, search, and query visual data. It provides detailed information about items, issues, and locations, even specifying if a finding was verified by an independent photo check.
Users connect via OAuth 2.1, signing in with Google, Apple, or email to authorize access without sharing raw keys. While the default connection is read-only, you can grant permission for the assistant to scan new spaces or access sensitive information like Wi-Fi passwords and alarm codes. The server uses Streamable HTTP and can be deployed on Cloudflare Workers to manage your data securely.
Beyond simple queries, the server allows for comparing different scans to identify changes and retrieving original video frames as photo evidence. It includes specialized tools for managing scan history, checking scan status, and even preparing checklists for filming specific environments like boats or appliances.
What you can do with it
- 1Find specific items with visual proofRequest the location of an object and ask the assistant to show the original photo evidence.
Written from the project's README. Every use case is checked against a quote from it.
How to install Space Context MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Space Context MCP in Claude Code
$ claude mcp add --transport http spacecontext https://mcp.spacecontext.app/mcpInstall Space Context MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"spacecontext": {
"url": "https://mcp.spacecontext.app/mcp"
}
}
}Install Space Context MCP in VS Code
.vscode/mcp.json
{
"servers": {
"spacecontext": {
"type": "http",
"url": "https://mcp.spacecontext.app/mcp"
}
}
}Install Space Context MCP in VS Code CLI
$ code --add-mcp '{"name":"spacecontext","type":"http","url":"https://mcp.spacecontext.app/mcp"}'Install Space Context MCP in Codex
$ codex mcp add spacecontext --url https://mcp.spacecontext.app/mcpInstall Space Context MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.spacecontext] url = "https://mcp.spacecontext.app/mcp"
Install Space Context MCP in Gemini CLI
$ gemini mcp add -s user --transport http spacecontext https://mcp.spacecontext.app/mcpInstall Space Context MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"spacecontext": {
"url": "https://mcp.spacecontext.app/mcp",
"type": "http"
}
}
}Space Context MCP tools 13
Detected from the READMElist_spacessearch_spacesget_spaceget_space_markdownask_spaceget_evidence_photowalletcapture_checklistcheck_framecreate_scanupload_framestart_scan
| list_spaces | — | |
| search_spaces | — | |
| get_space | — | |
| get_space_markdown | — | |
| ask_space | — | |
| get_evidence_photo | — | |
| wallet | — | |
| capture_checklist | — | |
| check_frame | — | |
| create_scan | — | |
| upload_frame | — | |
| start_scan | — |
Show all 13 toolsShow fewer tools
cancel_scan
| cancel_scan | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefinikoslab/spacecontext is public and reachablegithub.com/finikoslab/spacecontext ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/finikoslab/spacecontext ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubSpace Context MCP server
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
| Client | How |
|---|---|
| Claude (claude.ai, Desktop) | Settings → Connectors → Add custom connector, paste the URL, Connect |
| Claude Code | claude mcp add --transport http --scope user spacecontext https://mcp.spacecontext.app/mcp, then /mcp → Authenticate |
| Codex | codex mcp add spacecontext --url https://mcp.spacecontext.app/mcp, then codex mcp login spacecontext |
| ChatGPT | Settings → Apps & Connectors → Advanced → Developer mode, then create a connector with the URL and OAuth |
| Cursor | "spacecontext": { "url": "https://mcp.spacecontext.app/mcp" } under mcpServers in ~/.cursor/mcp.json, then Login in Cursor's MCP settings |
| VS Code | code --add-mcp '{"name":"spacecontext","type":"http","url":"https://mcp.spacecontext.app/mcp"}' (or servers in a workspace's .vscode/mcp.json), then MCP: List Servers → start it and sign in |
You never paste a key. Connecting works like this:
- 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.
- 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.
- The server creates an API key for this connection only, listed as
MCP · <assistant>in the console. Its scopes arespaces:readandscans:read, plusspaces:sensitiveandscans:writeif 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):
| Tool | |
|---|---|
list_spaces |
Spaces with their latest scan, 50 per page |
search_spaces |
The records that best answer a question, across all spaces or one, in any language |
get_space |
A space by section (areas, items, issues, key locations, instructions, facts, Q&A, coverage), optionally with evidence |
get_space_markdown |
The whole space as one Markdown page, to load it as context in one call |
ask_space |
A short answer with citations, or documented: false |
list_scans, compare_scans |
The scan history, and what changed between two scans, with evidence from both |
get_evidence_photo |
The original video frame behind a record, as an image |
get_scan_status, follow_scan |
Where a scan is; follow_scan waits on the event stream and reports progress |
wallet |
Balance, free scans left, price of a scan |
capture_checklist |
What to film for a type of space (a flat, a car, a boat, an appliance…), before a scan |
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:
| Tool | |
|---|---|
check_frame |
Is this photo usable, and which key locations does it show (with space_type, those of that type and the area); nothing is stored or charged |
create_scan |
Declares a scan of an existing or a new space and returns the upload instructions |
upload_frame |
Sends one image of a frames scan through the server, which holds the key |
start_scan |
Starts and charges a scan: the free scan first, then $1.00 from the balance; refunded if it fails |
cancel_scan |
Cancels a scan that hasn't started; nothing is charged |
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 install
npm 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/mcp
npx wrangler kv namespace create OAUTH_KV
3. Set the configuration in wrangler.jsonc (name, the custom domain in routes, and vars):
API_BASE_URL |
The API base, for example https://api.spacecontext.app/v1 |
PUBLIC_URL |
This server's origin. It names the protected resource (/.well-known/oauth-protected-resource/mcp) and is the only origin the consent forms accept posts from |
GOOGLE_WEB_CLIENT_ID |
Optional: the Google web OAuth client for "Continue with Google" |
APPLE_SERVICES_ID |
Optional: the Services ID for "Sign in with Apple" |
BACKEND (services) |
Optional: a service binding to the API Worker. Through it, the API sees each user's own IP for its rate limits and sign-in protection. Without it, the server calls API_BASE_URL over the internet and every user shares the Worker's IP. Remove the entry if the API isn't a Worker in your account |
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/callbackas an authorized redirect URI of the web OAuth client. - Apple: add
${PUBLIC_URL}/authorize/apple/callbackas 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_publicstays on. The server fetches client metadata documents from URLs that clients choose, so a plainfetchmust never reach private addresses. The API is reached through theBACKENDbinding.- With
workers_devandpreview_urlsoff, the server answers only on its custom domain. ratelimitslimit each client IP to 10 registrations (/register) and 60 sign-in page requests (/authorize…) a minute, answered with429andRetry-After: 60beyond. Rate limits aren't inherited by environments, and eachnamespace_idmust be unique in your Cloudflare account. Without the bindings (as indev) 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:8787
npm 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.
Space Context MCP questions
How do I add Space Context MCP to Claude Code?
Run claude mcp add --transport http spacecontext https://mcp.spacecontext.app/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Space Context MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Space Context MCP provide?
It exposes 13 tools, including list_spaces, search_spaces, get_space, get_space_markdown, ask_space.
Can the AI assistant see sensitive information like Wi-Fi passwords?
By default, the assistant cannot see sensitive values like Wi-Fi passwords or door codes unless you explicitly grant permission during the connection process.