Overview

Duckfly MCP is a local MCP (Model Context Protocol) server that uses the spec produced by Duckfly Core for your documented API. It exposes tools, prompts, and resources to AI clients and forwards tool calls to your backend.

Use the same Duckfly token as the proxy plugin. The spec is fetched once at startup from Duckfly Core.

Why use Duckfly MCP

• Expose your API as MCP tools so AI assistants can call your endpoints
• No manual MCP spec: tools and schemas come from your Duckfly documentation
• Two transport modes: stdio (for Claude Desktop, Cursor, etc.) and HTTP (Streamable HTTP + SSE)
• Optional auth (HTTP mode): None, Basic, Bearer, or OAuth (JWT via JWKS)
• CLI with hybrid mode: pass arguments via command line, and the CLI will ask only for what is missing
• Snapshot support: save the spec locally and run offline without a token

Quick Start

Global install

npm install -g @duckfly/mcp

Or run with npx

npx @duckfly/mcp

Interactive mode

When you run the CLI without arguments, it will guide you through the setup:

| Prompt | Description | Default | |---|---|---| | Token | Your Duckfly application token | | | Version | Which spec version to use (v1, v2...) | Main version | | Mode | Transport mode: HTTP or stdio | http | | Port | Port where the MCP server listens (HTTP only) | 9090 | | Upstream URL | Base URL of your API (tool calls are sent here) | App URL from token | | Default subdomain | Fallback subdomain when upstream uses wildcard (e.g. api) | Only if upstream has * | | Auth mode | None / Basic / Bearer / OAuth (HTTP only) | none |

Configuration is saved in .duckfly-mcp.json.

Command line mode

You can pass all options via CLI arguments. The CLI will only ask for what is missing.

# Full command line (no prompts)
duckfly-mcp --token abc123 --version 1 --mode http --port 9090 --upstream http://localhost:3000 --auth none

# Hybrid: pass what you know, it asks the rest
duckfly-mcp --token abc123 --mode http

# Stdio mode
duckfly-mcp --token abc123 --version 1 --mode stdio --upstream http://localhost:3000

All available flags:

| Flag | Description | |---|---| | --token <token> | Duckfly application token | | --version <N> | Spec version number (e.g. 1, 2) | | --mode <http\|stdio> | Transport mode (default: http) | | --port <N> | MCP port (default: 9090, HTTP only) | | --upstream <url> | Base URL for proxying tool calls (accepts wildcard if app domain allows) | | --default-subdomain <sub> | Default subdomain when upstream is wildcard | | --auth <mode> | Auth mode: none, basic, bearer, oauth (HTTP only) | | --auth-user <user> | Basic auth username | | --auth-pass <pass> | Basic auth password | | --auth-token <token> | Bearer auth token | | --oauth-issuer <iss> | OAuth issuer (iss claim) | | --oauth-jwks <url> | JWKS URL for JWT validation | | --oauth-audience <aud> | OAuth audience (optional) | | --oauth-auth-server <url> | Authorization Server URL | | --snapshot [file] | Download spec and save locally | | --from-snapshot [file] | Start using a saved spec (no token needed) | | --help | Show help |

Transports

Stdio (recommended for local use)

Stdio mode communicates via stdin/stdout using newline delimited JSON RPC. This is the standard way to integrate with Claude Desktop, Cursor, and similar AI clients.

No port or auth configuration is needed. The process pipe is inherently secure.

Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y", "@duckfly/mcp",
        "--mode", "stdio",
        "--token", "YOUR_TOKEN",
        "--version", "1",
        "--upstream", "http://localhost:3000"
      ]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "my-api": {
      "command": "duckfly-mcp",
      "args": [
        "--mode", "stdio",
        "--token", "YOUR_TOKEN",
        "--version", "1",
        "--upstream", "http://localhost:3000"
      ]
    }
  }
}

HTTP (Streamable HTTP + SSE)

HTTP mode starts an Express server with JSON RPC over HTTP. Supports SSE for streaming responses.

duckfly-mcp --token abc123 --version 1 --mode http --port 9090 --upstream http://localhost:3000

Endpoints

| Method | Path | Description | |---|---|---| | GET | /mcp | Open the global SSE channel (one at a time). | | POST | /mcp | JSON RPC. With Accept: text/event-stream you get a streamed response; otherwise, if the global SSE is open, the response is sent there and the POST gets 202; else you get application/json. | | DELETE | /mcp | End the session (requires Mcp-Session-Id). | | GET | /.well-known/oauth-protected-resource/mcp | OAuth protected resource metadata (only when OAuth is enabled). | | GET | /health | Health check ({ "ok": true }). |

Snapshot (offline mode)

You can save the spec locally and run the MCP server without needing a token or connection to Duckfly Core.

Save a snapshot

duckfly-mcp --snapshot --token abc123 --version 1

This downloads the spec and saves it to .duckfly-mcp-snapshot.json. You can also specify a custom path:

duckfly-mcp --snapshot ./my-spec.json --token abc123 --version 1

Note: The snapshot is a point in time copy of your spec. It may become outdated as your API evolves. We recommend updating it periodically or using live mode (without --from-snapshot) for the most up to date version.

Run from a snapshot

# HTTP mode
duckfly-mcp --from-snapshot --mode http --port 9090 --upstream http://localhost:3000

# Stdio mode
duckfly-mcp --from-snapshot --mode stdio --upstream http://localhost:3000

# Custom snapshot file
duckfly-mcp --from-snapshot ./my-spec.json --mode stdio --upstream http://localhost:3000

No token is required when running from a snapshot.

How it works

┌─────────────┐           Duckfly Spec         ┌──────────────┐
│ Duckfly MCP │ <───────────────────────────── │ Duckfly Core │
│ (local)     │                                │ (your spec)  │
└──────┬──────┘                                └──────────────┘
       │
       │ Tool calls (e.g. POST /api/users/123)
       ▼
┌──────────────┐
│ Your API     │  (Upstream URL)
└──────────────┘

1. At startup, the plugin fetches the MCP spec from Duckfly Core (tools, prompts, resources).
2. AI clients connect to your local MCP server and see those tools.
3. When a client invokes a tool, the server calls upstream URL + path (e.g. http://localhost:3001 + /api/users/123).
4. The response is returned to the client. The body includes a requested field (method + URL) for debugging.

Wildcard domains

If your application uses a wildcard domain (e.g. https://*.example.com), the MCP plugin resolves the actual URL for each tool call using the domain configured at each route and method level in your Duckfly spec:

1. If the endpoint (method) has a specific domain configured, that domain is used.
2. If the endpoint does not have one, but the route does, the route domain is used.
3. If neither has a specific domain, the wildcard is replaced with the default subdomain you configured.

For example, with upstream https://*.example.com and default subdomain api:

• GET /users with endpoint domain https://users.example.com → calls https://users.example.com/users
• POST /orders with no specific domain → calls https://api.example.com/orders

Troubleshooting

Tool call returns 404: The upstream server does not have that route. Make sure the service at the upstream URL is the same API that Duckfly observes, and if your API uses a prefix (e.g. /v1), set the upstream URL to http://localhost:3001/v1.

AggregateError on token validation: The Duckfly API server is not reachable. Check that the server is running and accessible.

License

MIT License

This license applies only to the Duckfly MCP package. The Duckfly platform and services are governed by separate terms.