# Spatial Compiler auth.md

This file describes how agents authenticate to the Spatial Compiler MCP servers and the REST API (`https://api.spatialcompiler.dev`), which Applied Manifold, Inc. operates.

The local MCP server reads a SPATIAL_API_KEY environment variable; the hosted server uses an OAuth 2.1 browser login. REST takes an API key as a bearer token. The local `spatial-compiler` program with the Claude plugin needs no credential.

## Audience

AI agents and automated pipelines (Claude Code, Cursor, CI jobs) that call Spatial Compiler over MCP or REST on behalf of a developer.

## API keys

- An API key is the credential for the local MCP server and for REST. New Sandbox keys come with 500 free credits.
- Code samples use the example key `sk_test_spatial_sandbox`; replace it with your own.
- `dry_run: true` calls and SHA-256 cache hits cost 0 credits, and each key has an hourly velocity limit.
- Treat a 401 as a revoked or invalid key and ask the developer for a new one.

## Local MCP server

- Package: `@spatial-compiler/mcp`, over stdio: `npx -y @spatial-compiler/mcp`.
- Credential: the API key in the `SPATIAL_API_KEY` environment variable (see https://appliedmanifold.com/docs/#mcp-local). A local stdio server takes its credential from the environment and runs no login flow.

## Hosted MCP server

- URL: https://mcp.spatialcompiler.dev (see https://appliedmanifold.com/docs/#mcp-hosted)
- Login: OAuth 2.1 in the browser to the developer's Applied Manifold account, with PKCE (`S256`) and the `authorization_code` and `refresh_token` grants.
- Protected resource metadata (RFC 9728, `resource` = https://mcp.spatialcompiler.dev): https://appliedmanifold.com/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414, `issuer` = https://mcp.spatialcompiler.dev): https://appliedmanifold.com/.well-known/oauth-authorization-server
- Client registration: dynamic client registration (RFC 7591) at https://mcp.spatialcompiler.dev/register, or a client ID metadata document.
- Authorize at https://mcp.spatialcompiler.dev/authorize and exchange the code at https://mcp.spatialcompiler.dev/token.
- The token is issued for https://mcp.spatialcompiler.dev only. Send it in the `Authorization: Bearer` header; an expired or bad token gets a 401, and too little scope gets a 403 with `error="insufficient_scope"`.

## REST API

- Host: https://api.spatialcompiler.dev (see https://appliedmanifold.com/docs/#rest)
- Send `Authorization: Bearer <API key>` in the header, never in a URL.
