Skip to content

Add AI agent tooling: skills, MCP servers, and docs #1015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mosch merged 1 commit into from
May 20, 2026
+391 −85
Merged

Add AI agent tooling: skills, MCP servers, and docs #1015

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 41 additions & 84 deletions docs/articles/ai-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Set up your Zuplo project for AI coding agents
title: AI Coding Agents
sidebar_label: AI Coding Agents
---

Expand All @@ -8,9 +8,19 @@ allowing AI coding agents to reference accurate, up-to-date APIs and patterns.
An `AGENTS.md` file at the root of your project directs agents to these bundled
docs instead of their training data.

For task-specific playbooks and Zuplo capabilities beyond documentation lookup,
see:

- [Agent Skills](../build-with-ai/skills.md) — install the official skills from
[`zuplo/tools`](https://github.com/zuplo/tools).
- [Docs MCP Server](../build-with-ai/docs-mcp-server.md) — real-time search and
Q&A across the full Zuplo documentation.
- [Zuplo MCP Server](../build-with-ai/zuplo-mcp-server.md) — manage your Zuplo
account programmatically from agents.

## How it works

When you install `zuplo`, the full Zuplo documentation is bundled at
Installing `zuplo` bundles the full Zuplo documentation at
`node_modules/zuplo/docs/`. The bundled docs cover policies, handlers, concepts,
guides, CLI reference, and more:

Expand Down Expand Up @@ -38,19 +48,26 @@ Code, Cursor, GitHub Copilot, Windsurf, and others — automatically read

### New projects

When you create a new project with `create-zuplo-api`, the `AGENTS.md` and
`CLAUDE.md` files are generated automatically. No additional setup is needed:
Creating a new project with `create-zuplo-api` generates the `AGENTS.md` and
`CLAUDE.md` files automatically. No additional setup is needed:

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

### Existing projects

Ensure you are on `zuplo` version `0.66.0` or later, then add the following
files to the root of your project.
Ensure you are on `zuplo` version `0.66.0` or later, then add `AGENTS.md` and
`CLAUDE.md` to the root of your project.

`AGENTS.md` contains the instructions that agents read:
Download the latest `AGENTS.md` directly from
[`zuplo/tools`](https://github.com/zuplo/tools):

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

Or create it manually — it contains the instructions that agents read:

```md title="AGENTS.md"
# Zuplo: ALWAYS read docs before coding
Expand Down Expand Up @@ -84,86 +101,26 @@ outdated training data.
You can add your own project-specific instructions to `AGENTS.md` or `CLAUDE.md`
alongside the Zuplo defaults.

## Install official skills

For a richer experience, install the official
[Zuplo agent skills](https://github.com/zuplo/tools). Skills provide
specialized, task-specific guidance that goes beyond general documentation
lookup — they teach agents how to set up projects, configure policies, write
handlers, set up monetization, and more.

### What are agent skills?

[Agent skills](https://agentskills.io) are structured instruction files that AI
coding agents load automatically. Each skill focuses on a specific domain and
includes step-by-step guidance, code patterns, and references to documentation.

### Available skills

| Skill | Description |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **zuplo-guide** | Comprehensive gateway guide — documentation lookup, request pipeline, route/policy configuration, custom handlers. |
| **zuplo-project-setup** | Step-by-step new project setup — scaffolding, routes, auth, rate limiting, CORS, env vars, deployment. |
| **zuplo-policies** | Policy configuration — built-in policy catalog, custom code policies, wiring policies to routes. |
| **zuplo-handlers** | Request handlers — URL forwarding/rewriting, redirects, custom TypeScript handlers, Lambda, WebSockets, MCP servers. |
| **zuplo-monetization** | API monetization — meters, plans, Stripe billing, subscriptions, usage tracking. |
| **zuplo-cli** | CLI reference — local dev, deployment, env vars, tunnels, OpenAPI tools, project management. |
| **zudoku-guide** | Comprehensive Zudoku framework guide — setup, configuration, OpenAPI integration, plugins, auth, theming. |

### Install skills

Install the skills from GitHub:

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

Or via `.well-known` discovery:

```bash
npx skills add https://zuplo.com/
```

After installation, agents automatically load the relevant skills when working
in your project.

## Optional: Add the MCP server

For search and Q&A across all Zuplo documentation, you can also add the Zuplo
MCP server. This gives agents the ability to search docs and ask questions in
real-time.

For **Claude Code**, add to `.claude/settings.json`:

```json title=".claude/settings.json"
{
"mcpServers": {
"zuplo-docs": {
"type": "http",
"url": "https://dev.zuplo.com/mcp/docs"
}
}
}
```

:::tip
## Going further

The MCP server is optional. The bundled docs in `node_modules/zuplo/docs/`
provide complete, version-matched documentation without any network requests.
The MCP server is useful for broader search and Q&A across all Zuplo
documentation.
Once `AGENTS.md` is in place, layer on the rest of Zuplo's agent tooling:

:::
1. [**Install the official skills**](../build-with-ai/skills.md) for
task-specific playbooks on project setup, policies, handlers, monetization,
and more.
2. [**Add the Docs MCP server**](../build-with-ai/docs-mcp-server.md) for
real-time search and Q&A across the full documentation.
3. [**Add the Zuplo MCP server**](../build-with-ai/zuplo-mcp-server.md) to let
agents drive your Zuplo account — deploy, manage API keys, inspect logs, and
more.

## Summary

There are three ways to give AI coding agents access to Zuplo documentation,
listed in priority order:
The recommended setup, in priority order:

1. **Bundled docs** (recommended) — always available at
`node_modules/zuplo/docs/`, version-matched, no setup required beyond
`AGENTS.md`
2. **Agent skills** — install from [zuplo/tools](https://github.com/zuplo/tools)
for task-specific guidance on project setup, policies, handlers,
monetization, and more
3. **MCP server** — add the Zuplo docs MCP server for real-time search and Q&A
1. **Bundled docs** — always available at `node_modules/zuplo/docs/`,
version-matched, no setup required beyond `AGENTS.md`.
2. **[Agent skills](../build-with-ai/skills.md)** — task-specific guidance from
[`zuplo/tools`](https://github.com/zuplo/tools).
3. **[MCP servers](../build-with-ai/overview.md)** — real-time docs search and
programmatic gateway management.
53 changes: 53 additions & 0 deletions docs/build-with-ai/docs-mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
title: Docs MCP Server
sidebar_label: Docs MCP Server
---

The Zuplo Docs MCP server exposes the full Zuplo documentation through the
[Model Context Protocol](https://modelcontextprotocol.io). AI agents can search,
ask questions, and pull in accurate, up-to-date answers without leaving the
editor.

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

This server is public — no authentication required.

## What it does

The Docs MCP server provides two tools:

| 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. The server returns a synthesized answer grounded in the docs. |

## Add it to your client

See the [Docs MCP Server setup guide](../../api/mcp-servers#docs-mcp-server) for
step-by-step instructions across Claude Desktop, Claude Code, and other MCP
clients. Any MCP-compatible client that accepts a streamable HTTP endpoint works
— no headers or credentials needed.

## When to use it

The Docs MCP server is most useful when:

- You want answers grounded in the **latest** docs, even when the agent's
training data is stale.
- You're working outside a Zuplo project, so the bundled
`node_modules/zuplo/docs/` isn't available.
- You want a one-question lookup ("How do I configure the rate-limit policy?")
without manually opening the docs site.

For project-local work, prefer the
[bundled docs in `node_modules/zuplo/docs/`](../articles/ai-agents.md) — they
match your installed Zuplo version and don't require a network round-trip.

## Related

- [AI Coding Agents](../articles/ai-agents.md) — how to set up `AGENTS.md` and
bundled docs.
- [Agent Skills](./skills.md) — task-specific guidance that complements the docs
MCP server.
- [Zuplo MCP Server](./zuplo-mcp-server.md) — manage your Zuplo account
programmatically from agents.
49 changes: 49 additions & 0 deletions docs/build-with-ai/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Build with AI
sidebar_label: Overview
---

Zuplo gives AI coding agents — Claude Code, Cursor, GitHub Copilot, Codex,
Windsurf, and others — first-class support for building, configuring, and
managing your API gateway. This section covers the tools, skills, and Model
Context Protocol (MCP) servers that make Zuplo agent-ready.

## What's included

| Tool | Purpose |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AI Coding Agents](../articles/ai-agents.md) | Configure `AGENTS.md` and use version-matched docs bundled with the `zuplo` npm package. |
| [Agent Skills](./skills.md) | Install the official Zuplo and Zudoku skills from [`zuplo/tools`](https://github.com/zuplo/tools) for task-specific agent guidance. |
| [Docs MCP Server](./docs-mcp-server.md) | Connect agents to `https://dev.zuplo.com/mcp/docs` for real-time search and Q&A across Zuplo documentation. |
| [Zuplo MCP Server](./zuplo-mcp-server.md) | Connect agents to `https://dev.zuplo.com/mcp` to manage accounts, deployments, API keys, custom domains, tunnels, and more through the Zuplo Developer API. |

## How the pieces fit together

The pieces are complementary — they work best when using them together:

1. **`AGENTS.md` and bundled docs** keep agents grounded in your project's
installed Zuplo version. No network calls required.
2. **Skills** add task-specific playbooks for common workflows (project setup,
policies, monetization, CLI usage).
3. **MCP servers** give agents live capabilities — searching the latest docs and
driving your Zuplo account programmatically.

:::tip

If you're starting fresh, run `npx create-zuplo-api@latest` — it scaffolds
`AGENTS.md` and `CLAUDE.md` for you. Then install the skills and add the MCP
servers as needed.

:::

## Quick start

Install the official skills:

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

Then connect the MCP servers — see [MCP Server setup](../../api/mcp-servers) for
client-specific instructions (Claude Desktop, Claude Code, and other MCP
clients).
131 changes: 131 additions & 0 deletions docs/build-with-ai/skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
---
title: Agent Skills
sidebar_label: Agent Skills
---

[Agent skills](https://agentskills.io) are structured instruction files that AI
coding agents load automatically. Each skill focuses on a specific domain and
includes step-by-step guidance, code patterns, and references to the relevant
documentation.

The official Zuplo skills live in
[`zuplo/tools`](https://github.com/zuplo/tools). They cover gateway
configuration, monetization, the CLI, and the Zudoku developer portal — so
agents have task-specific playbooks instead of relying on training data that may
be out of date.

## Available skills

### Zuplo

| Skill | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **zuplo-guide** | Comprehensive gateway guide — documentation lookup, request pipeline, route and policy configuration, custom handlers, and deployment. Start here for general Zuplo development. |
| **zuplo-monetization** | API monetization — meters, plans, Stripe billing, subscriptions, usage tracking, private plans, and tax collection. |
| **zuplo-cli** | CLI reference — local development, deployment, environment variables, tunnels, OpenAPI tools, mTLS, and project management. |

### Zudoku (Developer Portal)

| Skill | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **zudoku-guide** | Comprehensive Zudoku framework guide — setup, configuration, OpenAPI integration, plugins, auth, theming, troubleshooting, and migrations. |

## Installation

### Claude Code

Register the repo as a plugin marketplace, then install the skills:

```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`. Or copy the skill directories into your
project:

```txt
.cursor/skills/
├── zuplo-guide/SKILL.md
├── zuplo-monetization/SKILL.md
├── zuplo-cli/SKILL.md
└── zudoku-guide/SKILL.md
```

Skills placed in `.cursor/skills/`, `.agents/skills/`, or `~/.cursor/skills/`
are auto-discovered.

### GitHub Copilot and VS Code

Copilot reads `AGENTS.md` at the repo root automatically. Add the Zuplo
`AGENTS.md` to your project for project-level context:

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

You can also use the `/create-skill` command in Copilot chat and reference the
skills in [`zuplo/tools`](https://github.com/zuplo/tools) as a starting point.

### Codex (OpenAI)

Codex reads `AGENTS.md` at the repo root. Add the Zuplo `AGENTS.md` to your
project so Codex picks up project-level context.

### Using the `skills` CLI

The cross-client
[`skills` CLI](https://github.com/cloudflare/agent-skills-discovery-rfc)
installs skills directly:

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

Or via `.well-known` discovery:

```bash
npx skills add https://zuplo.com/
npx skills add https://zudoku.dev/
```

### Manual install

```bash
git clone https://github.com/zuplo/tools.git
```

Then copy the skill directories you need into your project's skills directory.

## How skills find documentation

All Zuplo skills look up documentation in this order:

1. **Local docs from `node_modules/zuplo/docs/`** (preferred). The `zuplo` npm
package ships with the full Zuplo documentation, version-matched to your
installed Zuplo version. See [AI Coding Agents](../articles/ai-agents.md) for
setup details.
2. **The [Zuplo Docs MCP server](./docs-mcp-server.md)** for search and Q&A
across the full documentation.
3. **Fetch docs via URL** as a fallback (`https://zuplo.com/docs/`).

:::tip

Combine the skills with the [Zuplo MCP server](./zuplo-mcp-server.md) to let
your agent both write the code and operate the gateway — for example, scaffold a
route locally, then deploy and inspect logs without leaving the session.

:::

## Contributing

The skills are MIT-licensed. To improve them:

1. Fork [`zuplo/tools`](https://github.com/zuplo/tools).
2. Update the relevant `SKILL.md` file.
3. Test with your own development workflow.
4. Open a pull request.
Loading
Loading