MCP server

What's there

• Endpoint: https://api.cimplify.io/mcp (single endpoint, POST/GET/DELETE per spec)
• Transport: Streamable HTTP, MCP protocol 2025-11-25
• Auth: Authorization: Bearer dk_… (same API keys the CLI uses)
• Session: server-assigned MCP-Session-Id header at initialize, echoed on every subsequent request

The full design lives in docs/tickets/mcp-server.md in the platform repo. Below is the customer-facing surface.

Connect

Claude Desktop / Claude Code

~/.config/claude/claude_desktop_config.json (Linux) or the equivalent on macOS/Windows:

{
  "mcpServers": {
    "cimplify": {
      "url": "https://api.cimplify.io/mcp",
      "headers": { "Authorization": "Bearer dk_live_xxx" }
    }
  }
}

Cursor

.cursor/mcp.json in any project root:

{
  "mcpServers": {
    "cimplify": {
      "url": "https://api.cimplify.io/mcp",
      "headers": { "Authorization": "Bearer dk_live_xxx" }
    }
  }
}

ChatGPT Connectors / Continue / Goose

Use the same url + Bearer header. Spec-compliant clients all accept this shape.

Headless agents

POST initialize with Origin set to one of the allowlisted hosts (or omitted for non-browser clients), MCP-Protocol-Version: 2025-11-25, and the Bearer token. The server returns MCP-Session-Id in the response headers; include it on every subsequent request.

Auth scopes

API keys must hold mcp:invoke to enter the MCP surface at all. Per-tool scopes are checked individually:

Create keys with the scopes you need at /v1/businesses/:bid/api-keys (REST). The dashboard surfaces this as a checkbox set.

Destructive ops

Three tools are tagged destructive:

• cimplify_unlink_repo (when purge=true, also deletes the upstream repo)
• cimplify_remove_env (data loss)
• cimplify_detach_domain

These refuse with DESTRUCTIVE_DENIED unless the target project has settings.mcp_destructive_ops_enabled = true. Flip via:

PUT /v1/businesses/:bid/projects/:pid
Content-Type: application/json
{ "settings": { "mcp_destructive_ops_enabled": true, ...existing settings } }

Opting in is never an MCP tool; agents can't enable their own destructive surface. Bootstrap from outside.

Idempotency

Write tools accepting idempotency_key (string) cache the response per-session for 1 hour. Same key + same input returns the same response without re-executing:

• cimplify_create_project
• cimplify_provision_repo
• cimplify_connect_repo
• cimplify_deploy
• cimplify_rollback
• cimplify_add_domain

Underlying services have their own dedup floor too: cimplify_deploy deduplicates by (project, git_sha, env_scope) regardless of the idempotency key.

Tool surface

26 tools total (12 reads, 14 writes). Discover at runtime via tools/list. Every tool's input schema is JSON Schema, exposed on the listing.

Resources

Four read-only URIs:

• cimplify://ctx: account + business + attached project snapshot
• cimplify://projects: first 100 projects in the business
• cimplify://projects/{id}: single project + repo + last deploy
• cimplify://docs: pointer to docs.cimplify.io/llms.txt. Fetch the URL via your standard WebFetch.

The docs surface is intentionally a pointer, not a proxy. The MCP server doesn't ship docs content; agents read it from docs.cimplify.io directly. The advantage: docs iterate independently of platform deploys.

Errors

JSON-RPC standard codes (-32700 parse error, -32600 invalid request, -32601 method not found, etc.) plus Cimplify-specific codes in the server-defined range:

End-to-end example

A typical agent session shipping a fresh storefront:

1. POST /mcp initialize                              → MCP-Session-Id assigned
2. POST /mcp tools/list                              → 26 tools
3. POST /mcp resources/read cimplify://docs           → docs URLs
4. (agent WebFetches docs.cimplify.io/llms.txt + relevant pages)
5. POST /mcp tools/call cimplify_create_project       → new project
6. POST /mcp tools/call cimplify_attach_project       → bind for subsequent calls
7. POST /mcp tools/call cimplify_provision_repo       → Freestyle repo URL
8. POST /mcp tools/call cimplify_set_env              → env vars for preview
9. POST /mcp tools/call cimplify_deploy               → deployment_id, status: queued
10. POST /mcp tools/call cimplify_get_deployment_status (poll until active)
11. POST /mcp tools/call cimplify_add_domain          → DNS records
    (customer publishes DNS)
12. POST /mcp tools/call cimplify_verify_domain       → verified
13. POST /mcp tools/call cimplify_attach_domain       → live

About 12 tool calls, no shell-out, no help-text parsing, fully observable in the agent's UI.

Capabilities advertised

initialize returns:

{
  "protocolVersion": "2025-11-25",
  "capabilities": {
    "tools":     { "listChanged": false },
    "resources": { "subscribe": false, "listChanged": false }
  },
  "serverInfo": { "name": "cimplify", "title": "Cimplify", "version": "..." }
}

resources.subscribe is advertised as false and will flip to true in a future PR when deployment-status push notifications land over SSE. Until then, poll cimplify_get_deployment_status. The server intentionally only advertises capabilities it implements — agents that probe capabilities.resources.subscribe see the truth.

Compared to the CLI

The CLI (@cimplify/cli) and the MCP server expose the same underlying capabilities through different transports:

• CLI: argv to process exit code + stdout. Best for humans, CI, scripts.
• MCP: JSON-RPC tool call to typed response. Best for agents.

Both go through the same backend services, the same scope checks, the same audit log. An agent that has API access to a project via the CLI has the same access via MCP, and vice versa. Choose by the consumer.

For agents that don't speak MCP natively, the CLI also has a --json flag that returns structured output on stdout, usable from any Bash tool. Install once with curl -fsSL https://cimplify.io/install | sh.