LEARN // MCP

Hosted vs local MCP server

A hosted MCP server runs on the provider's side at a URL, and your client connects over HTTP, often with a browser sign-in and no key in your config. A local MCP server is a program your client starts on your computer, talking over standard input and output, usually with an API key in an environment variable.

A draft compile is from $0.05, and new accounts start with $5 of usage.

AT A GLANCE
  • Hosted: a URL and a browser sign-in (OAuth)
  • Local: a command your client starts, key in an env var
  • Spatial Compiler offers both, in early access
  • Both send work to the same hosted API

01 // THE DIFFERENCE

What changes between the two

  • Setup: a hosted server needs a URL in the config. A local one needs a runtime such as Node.js and a command such as npx.
  • Sign-in: hosted servers can use OAuth, so you sign in once in a browser. Local servers usually read a key from the environment.
  • Reach: a local server can touch files and programs on your machine, while a hosted one sees only what your agent sends it.
  • Clients: every MCP client can start local servers, and most current clients also connect to remote servers over HTTP.

02 // CONFIG

The two Spatial Compiler configs

Both go in your MCP client's server list. The hosted entry holds no key, and your client opens a browser sign-in the first time.

mcp.json (hosted)
{
  "mcpServers": {
    "spatial-compiler": {
      "type": "http",
      "url": "https://spatialcompiler.dev/mcp"
    }
  }
}
mcp.json (local)
{
  "mcpServers": {
    "spatial-compiler": {
      "command": "npx",
      "args": [
        "-y",
        "@applied-manifold/spatial-compiler"
      ],
      "env": {
        "SPATIAL_API_KEY": "spck_test_example"
      }
    }
  }
}

Replace spck_test_example with your API key. The local server runs no compiles on your machine; it sends every call to the hosted API and is billed the same.

03 // SPATIAL COMPILER

Which one to pick for Spatial Compiler

Pick the hosted server when your client supports remote servers, since there is no key to store or rotate. Pick the local server for a client that only starts local commands, or for CI and scripts where a browser sign-in cannot happen. Either way, ask your agent for an effect and you get the same sprite sheets. See Install via MCP.

05 // FAQ

Hosted and local MCP questions

All questions →

README.HOSTED_VS_LOCAL_MCP
When should I use a hosted MCP server instead of a local one?

Use hosted when your client supports remote servers without storing a key. Use local when your client only runs local commands.

How do I configure authentication for hosted and local MCP servers?

For a hosted server, add the URL and complete browser sign in. For a local server, set your API key in the environment.

How do I add an MCP server to my client?

Add a server entry with a URL for hosted servers or a command and arguments for local ones, then restart the client.

Do I start the Spatial Compiler MCP server from inside my game engine?

No. Only editor plugin servers run inside the engine. Spatial Compiler runs outside your engine as a hosted or local server.

Which MCP clients can connect to the hosted Spatial Compiler server?

Any client supporting remote MCP servers over HTTP with browser sign in can connect. Other clients can run the local package.

Compile your first effect

You pay per compile and see the price before it runs. New accounts start with $5 of usage.

All effects, guides and explainers →