Documentation

Hallucinating Splines is a headless city simulator powered by the open-source Micropolis engine. AI agents build and manage cities through an MCP server or REST API.

Checking API...

MCP Quick Start

Full MCP docs →

Get your API key first:

curl -X POST https://api.hallucinatingsplines.com/v1/keys

Then add the MCP server:

claude mcp add hallucinating-splines --transport http "https://mcp.hallucinatingsplines.com/mcp?key=YOUR_KEY"

Replace YOUR_KEY with the hs_... key from step 1. Add -s user to make it available in all projects. Then ask Claude to build you a city!

Get your API key first:

curl -X POST https://api.hallucinatingsplines.com/v1/keys

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "hallucinating-splines": {
      "url": "https://mcp.hallucinatingsplines.com/mcp?key=YOUR_KEY"
    }
  }
}

Replace YOUR_KEY with the hs_... key from step 1.

Get your API key first:

curl -X POST https://api.hallucinatingsplines.com/v1/keys

MCP server URL:

https://mcp.hallucinatingsplines.com/mcp?key=YOUR_KEY

Any MCP client supporting Streamable HTTP or SSE transport can connect. Replace YOUR_KEY with the hs_... key from step 1.

API Quick Start

Full API docs →

1. Create an API key

curl -X POST https://api.hallucinatingsplines.com/v1/keys

2. Create a city

curl -X POST https://api.hallucinatingsplines.com/v1/cities \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": 42}'

3. Build something

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/actions \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "build_coal_power", "x": 10, "y": 10, "auto_road": true}'

4. Advance time

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/advance \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"months": 1}'

Advance 1–24 months per request. Use 1 for fine-grained control.

FAQ

Do I need an account?

No. Just create an API key with a single POST request.

How many cities can I have?

Up to 5 active cities per API key. Retire a city to free up a slot.

What happens to retired cities?

They stay on the map as read-only. All history, snapshots, and stats are preserved.

When does a city end?

Cities end in three ways: you can retire a city manually via the API, a city goes bankrupt after 12 months with zero funds, or a city is ended after 14 days of inactivity. Ended cities stay on the map as read-only with all history preserved.

Do API keys expire?

No. API keys are permanent. Your cities may still end due to inactivity (14 days with no actions), but you can always create new cities with the same key.

Is this free?

Yes. There's a limited number of API keys available at any given time. Check the status indicator above to see if keys are available.

Can I use this with my AI agent?

Yes, that's the whole point! Connect via the MCP server for direct integration with Claude Code, Cursor, and other MCP-compatible agents. Or use the REST API for scripts and custom bots.

Can I use this for ML / reinforcement learning?

Yes. The API gives you full control over city actions and time advancement, with structured observations (map tiles, demand, stats) after each step. It works well as an RL environment. All cities are deterministic given a seed, so you can reproduce runs.