MCP Server

Shape provides an MCP-compatible HTTP server through shape-mcp. It is designed for AI tool integration — exposing Shape’s query engine over a simple REST API that language models and external agents can call directly.

Start

cargo run -p shape-mcp --bin shape-mcp-server

By default it binds to 127.0.0.1:8080.

Override host/port:

cargo run -p shape-mcp --bin shape-mcp-server -- --host 0.0.0.0 --port 8080

Core Endpoints

GET /health

Returns 200 OK with a JSON body when the server is running.

curl http://localhost:8080/health
# {"status":"ok","version":"0.1.0"}

POST /query

Execute a Shape expression and return the result.

Request body:

{
  "query": "let data = [1, 2, 3]\ndata.mean()",
  "data": {}
}

Response:

{
  "result": 2.0,
  "elapsed_ms": 3
}

Example:

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "[10, 20, 30].sum()"}'
# {"result":60,"elapsed_ms":1}

GET /ai/list_stdlib

Returns a machine-readable listing of all available stdlib modules and their exported functions. Useful for priming a language model’s context with the Shape API surface.

curl http://localhost:8080/ai/list_stdlib
# {"modules":{"std:io":[...],"std:time":[...],...}}

POST /ai/validate

Parse and type-check a Shape snippet without executing it. Returns any compile-time errors so an AI agent can iterate on code before running it.

Request body:

{
  "code": "let x: int = \"oops\""
}

Response (error):

{
  "valid": false,
  "errors": [
    {"line": 1, "col": 16, "message": "type mismatch: expected int, got string"}
  ]
}

Example:

curl -X POST http://localhost:8080/ai/validate \
  -H "Content-Type: application/json" \
  -d '{"code": "fn add(a: int, b: int) -> int { a + b }"}'
# {"valid":true,"errors":[]}

POST /ai/execute

Validate, compile, and execute a Shape snippet in one step. Returns the result or any errors.

Request body:

{
  "code": "fn double(x: int) -> int { x * 2 }\ndouble(21)"
}

Response:

{
  "result": 42,
  "elapsed_ms": 2,
  "errors": []
}

Example:

curl -X POST http://localhost:8080/ai/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "[1,2,3,4,5].filter(|x| x > 2).map(|x| x * 10)"}'
# {"result":[30,40,50],"elapsed_ms":1,"errors":[]}

Execution Backend

By default, shape-mcp shells out to shape run for code execution. For lower latency, you can point it at a running shape serve instance instead:

# Start the execution server
shape serve

# Start MCP with the wire backend
SHAPE_SERVE_ADDR=127.0.0.1:9527 shape-mcp

When SHAPE_SERVE_ADDR is set, the MCP server sends code to the execution server via MessagePack-over-TCP (the standard wire framing protocol). This eliminates per-request process startup overhead.

	CLI mode (default)	Wire mode (SHAPE_SERVE_ADDR)
Startup	Spawns shape run per request	Persistent TCP connection
Dependencies	shape binary on PATH	Running shape serve
Latency	~100-300ms (process spawn)	~1-10ms (in-process VM)
Fallback	—	Error if server unreachable (no silent fallback)

Authentication

The MCP server has no authentication in its current form. It is designed for local use only (loopback interface). If you bind to 0.0.0.0 or expose it through a tunnel, any client on the network can execute arbitrary Shape code — treat this equivalently to exposing a shell.

For production deployments, place the server behind a reverse proxy with authentication (e.g., nginx with auth_basic or a bearer-token check).

MCP Server vs shape-server

	shape-mcp	shape-server
Purpose	AI tool / agent integration	Book REPL and notebook backend
Protocol	HTTP/REST JSON	Internal WebSocket
Auth	None (local only)	Session-scoped
Use when	Connecting LLM agents	Running the book or REPL UI

Use shape-mcp when you are building a tool that lets an AI assistant read, validate, or execute Shape code. Use shape-server for interactive development with the book UI or REPL.

See Also

• Execution Server — shape serve command reference
• Wire Protocol — framing, compression, blob negotiation