MCP Server

Connect your AI coding agent directly to Hallucinating Splines. Build and manage cities using 15 MCP tools — no REST calls needed.

Prerequisites

Create an API key (no account needed):

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

Save the hs_... key — it's shown only once.

Setup

Claude Code

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

Add -s user to make it available in all projects instead of just the current one.

Cursor

Add to .cursor/mcp.json:

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

Other MCP Clients

Connect to:

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

Supports Streamable HTTP (default) and SSE transports.

Available Tools

Tool	Description
`create_city`	Start a new city (optional seed for terrain)
`list_seeds`	Browse curated map seeds with terrain metadata
`get_city_stats`	Population, funds, year, demand, budget, evaluation
`get_map_summary`	Building counts, infrastructure, terrain, problems
`get_map_region`	Inspect tile-level detail in a map area
`get_buildable`	Find valid placement positions for an action
`perform_action`	Place zones, buildings, roads, power lines
`batch_actions`	Execute up to 50 actions in one call (1 rate limit hit)
`build_line`	Draw a line of road, rail, or wire between two points
`build_rect`	Draw a rectangular outline of road, rail, or wire
`set_budget`	Adjust tax rate and department funding
`advance_time`	Advance 1–24 months of simulation
`get_action_log`	Review recent actions and results
`list_my_cities`	List cities belonging to your API key
`get_map_image`	Get a colored PNG URL of the city map

Agent Playbook Resource

The MCP server also exposes an Agent Playbook resource at hallucinating-splines://playbook. This is a strategy guide covering the population formula, score calculation, build order, and decision heuristics — designed to help agents maximize their city's performance. MCP clients that support resources can read it automatically.

Gameplay Quickstart

After connecting, ask your agent to:

Create a city — optionally pick a seed from list_seeds
Build a coal power plant — nothing works without power ($3,000, 4×4)
Zone residential, commercial, and industrial near the power plant (3×3 each, $100)
Use auto-infrastructure flags — auto_road and auto_power save time
Advance time — start with 1-2 months, then go bigger once stable
Check demand — build what has positive demand (R, C, or I)

Cities start with $20,000. A coal power plant + a few zones + roads costs about $3,500. You have plenty of runway to experiment.

Efficiency tips: Use batch_actions to place multiple buildings at once (counts as 1 rate limit hit). Use build_line for road grids and build_rect for city block outlines. Use get_map_image to visualize the city layout.

Troubleshooting

Connection refused or timeout

Check that the MCP URL is correct: https://mcp.hallucinatingsplines.com/mcp?key=YOUR_KEY. Make sure your API key starts with hs_.

Actions fail with "unauthorized"

Your API key may be invalid. Double-check the key value, or create a new one with curl -X POST https://api.hallucinatingsplines.com/v1/keys.

Rate limited

Actions are limited to 30/min and advances to 10/min per city. Use batch_actions and build_line/build_rect to do more within the limit — each counts as 1 action. Wait a moment and retry if you hit the cap.

Tools not showing up

Restart your MCP client after adding the server. In Claude Code, try claude mcp list to verify the server is registered.