# Build with AI

AI coding agents — Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and
others — have first-class support for building and operating Zuplo APIs. This
page lists the resources that keep agents grounded in accurate, up-to-date Zuplo
knowledge instead of stale training data.

The pieces are complementary. Start with `AGENTS.md` and the bundled docs, then
layer on skills and MCP servers as needed.

## AGENTS.md and bundled docs

The `zuplo` npm package ships the full documentation at
`node_modules/zuplo/docs/`, version-matched to the Zuplo version installed in
your project. An `AGENTS.md` file at the repo root tells agents to read those
docs before writing any code — no network calls required.

New projects scaffold both files automatically:

```bash
npx create-zuplo-api@latest
```

For existing projects on `zuplo` 0.66.0 or later, drop in the default
`AGENTS.md`:

```bash
curl -o AGENTS.md https://raw.githubusercontent.com/zuplo/tools/main/AGENTS.md
```

Claude Code users get the same instructions by importing `AGENTS.md` from
`CLAUDE.md`:

```md title="CLAUDE.md"
@AGENTS.md
```

The bundled `node_modules/zuplo/docs/` tree covers concepts, policies, handlers,
articles, CLI reference, the developer portal, guides, and the programmable API
— everything an agent needs to write correct Zuplo code without guessing.

## Agent Skills

[Agent skills](https://agentskills.io) are structured instruction files that
agents load automatically. The official Zuplo skills live in
[`zuplo/tools`](https://github.com/zuplo/tools) and cover gateway configuration,
monetization, the CLI, and the Zudoku developer portal.

Install all of them with the cross-client
[`skills` CLI](https://github.com/cloudflare/agent-skills-discovery-rfc):

```bash
npx skills add zuplo/tools
```

| Skill                  | Description                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **zuplo-guide**        | Documentation lookup, request pipeline, route and policy configuration, custom handlers, and deployment. Start here.   |
| **zuplo-monetization** | Meters, plans, Stripe billing, subscriptions, usage tracking, private plans, and tax collection.                       |
| **zuplo-cli**          | Local development, deployment, environment variables, tunnels, OpenAPI tools, mTLS, and project management.            |
| **zudoku-guide**       | Zudoku framework — setup, configuration, OpenAPI integration, plugins, auth, theming, troubleshooting, and migrations. |

Client-specific installation:

- **Claude Code** — register the marketplace, then install:

  ```bash
  /plugin marketplace add zuplo/tools
  /plugin install zuplo-skills@zuplo-tools
  /plugin install zudoku-skills@zuplo-tools
  ```

- **Cursor** — open **Cursor Settings → Rules → Add Rule → Remote Rule
  (GitHub)** and enter `https://github.com/zuplo/tools`. Skills placed in
  `.cursor/skills/`, `.agents/skills/`, or `~/.cursor/skills/` are
  auto-discovered.
- **GitHub Copilot, Codex, and other agents** — these read `AGENTS.md` at the
  repo root automatically. The Zuplo `AGENTS.md` (see above) is enough to point
  them at the bundled docs.

Skills look up documentation in this order: bundled docs in
`node_modules/zuplo/docs/`, then the Docs MCP server below, then a URL fetch to
`https://zuplo.com/docs/` as a fallback.

## Docs MCP Server

The Docs MCP server exposes the full Zuplo documentation through the
[Model Context Protocol](https://modelcontextprotocol.io). It's public, with no
authentication required.

**Endpoint:** `https://dev.zuplo.com/mcp/docs`

| Tool                       | Purpose                                                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `search-zuplo-docs`        | Semantic search across all Zuplo documentation. Useful for finding pages on policies, handlers, and concepts. |
| `ask-question-about-zuplo` | Ask a natural-language question. Returns a synthesized answer grounded in the docs.                           |

Add it to any MCP-compatible client by pointing the client at the endpoint as a
streamable HTTP server. For project-local work, prefer the bundled
`node_modules/zuplo/docs/` — they match your installed version and don't need a
network round-trip.

## Zuplo MCP Server

The Zuplo MCP server exposes the [Zuplo Developer API](https://dev.zuplo.com)
through MCP. Agents can manage accounts, deployments, API keys, custom domains,
tunnels, audit logs, and analytics in a single authenticated session.

**Endpoint:** `https://dev.zuplo.com/mcp`

:::caution

Unlike the Docs MCP server, this server performs real operations against your
Zuplo account. Connecting an agent gives it the same permissions as the API key
you authenticate with — scope the key tightly and treat it like any other
production credential.

:::

Authenticate with a [Zuplo API key](./articles/accounts/zuplo-api-keys.md).
Create one in the Zuplo Portal under
[**Account Settings → API Keys**](https://portal.zuplo.com/+/account/settings/api-keys),
then pass it as a bearer token:

```http
Authorization: Bearer <ZUPLO_API_KEY>
```

Capabilities include:

| Area                  | What agents can do                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------ |
| **Accounts**          | List accounts and identify the caller (`WhoAmI`).                                          |
| **Projects**          | List projects and environments in an account.                                              |
| **Deployments**       | List, read, redeploy, and delete deployments. Upload sources and check deployment status.  |
| **API Key Buckets**   | Create, list, read, update, and delete API key buckets.                                    |
| **API Key Consumers** | Create, list, read, update, delete, and roll keys for consumers. Manage consumer managers. |
| **API Keys**          | Create (single or bulk), list, read, update, and delete keys for a consumer.               |
| **Custom Domains**    | Create, list, update, and delete custom domains.                                           |
| **Client mTLS CAs**   | Create, list, update, and delete client mTLS CA certificates.                              |
| **Tunnels**           | Create, list, read, update, and delete tunnels. Configure and inspect tunneled services.   |
| **Variables**         | Create and update environment variables on a project branch.                               |
| **Audit Logs**        | Query audit logs with filtering and pagination.                                            |
| **Analytics**         | Get recent calls and request statistics by status code for a deployment.                   |

The tool catalog is generated from the Developer API's OpenAPI spec, so new
endpoints become available automatically as the API ships them.

Example prompts:

- _"List all deployments in the `production` environment of project `my-api`."_
- _"Create a new API key consumer named `acme-corp` and generate a key that
  expires in 30 days."_
- _"Show me the request stats by status code for the latest deployment over the
  last 24 hours."_
- _"Set the environment variable `STRIPE_API_KEY` on the `main` branch."_