For agents

MCP server, llms.txt, and markdown mirrors — the docs are built to be operated by AI agents, not just read by humans.

For agents

Vortex is built agent-first: an AI coding agent pointed at these docs can discover, read, and operate the whole surface without a human copy-pasting in the middle.

There are two MCP servers: one to read the docs, one to operate the API.

API MCP server (operate)

Typed tools for the whole merchant API — customers, subscriptions, invoices, checkout, coupons, credit notes, merchant accounts, webhooks. Authenticate with a Vortex API key; the key carries its environment, so a sandbox key cannot touch production.

Claude Code

claude mcp add --transport http vortex https://api.vortex.nyc/mcp   --header "Authorization: Bearer $VORTEX_API_KEY"

Cursor / Codex / any client

{
  "mcpServers": {
    "vortex": {
      "url": "https://api.vortex.nyc/mcp",
      "headers": { "Authorization": "Bearer vp_test_..." }
    }
  }
}

Every tool call is a real API call: authenticated, scope-checked, and recorded in your request logs with a requestId — the same call you would make with the SDK. Mutating calls carry a generated Idempotency-Key, so a retrying agent cannot double-charge anyone. The operator control plane is generated out of the tool surface entirely and cannot appear there.

Docs MCP server (read)

The docs ship a hosted MCP server at https://vortex.nyc/payments/docs/mcp — search and read every guide and reference page as tools.

Claude Code

claude mcp add --transport http vortex-docs https://vortex.nyc/payments/docs/mcp

Cursor

{
  "mcpServers": {
    "vortex-docs": {
      "url": "https://vortex.nyc/payments/docs/mcp"
    }
  }
}

Codex

[mcp_servers.vortex-docs]
url = "https://vortex.nyc/payments/docs/mcp"

Any client (mcp-remote)

{
  "mcpServers": {
    "vortex-docs": {
      "command": "npx",
      "args": ["mcp-remote", "https://vortex.nyc/payments/docs/mcp"]
    }
  }
}

llms.txt and markdown mirrors

• https://vortex.nyc/payments/docs/llms.txt — the full index: every guide and every API reference operation, one line each.
• Every page is dual-served as markdown: append .md to any docs URL.
• https://vortex.nyc/payments/docs/agent-readability.json — machine-readable discovery manifest for all of the above.

Coverage is asserted on every docs build (reference page count ≥ public spec operation count), so the index cannot silently fall behind the API.

Operate, not just read

• The public OpenAPI spec (with runnable x-codeSamples on every operation) backs the reference — agents can generate calls directly.
• npx @vortexnyc/payments-create scaffolds a running integration; npx @vortexnyc/payments-migrate plans and executes a Stripe migration (dry-run by default — safe for an agent to run); npx @vortexnyc/payments-listen delivers real signed webhooks to localhost.
• Keys carry their environment (vp_test_ = sandbox), so an agent holding a sandbox key cannot touch production by mistake.