Skip to main content
Duckie’s MCP endpoint exposes the read-only Duckie API as Model Context Protocol tools. Use it when an MCP client needs to inspect Duckie runs, tools, agents, guidelines, guardrails, or runbooks without calling each REST endpoint directly.

​
Endpoint

https://app.useduckie.ai/api/mcp
Send JSON-RPC requests with POST. For direct MCP clients that let you configure headers, authenticate with a customer API key. 
Authorization: Bearer dk_live_your_api_key
Content-Type: application/json
Create and manage customer API keys from Settings -> API Access. The endpoint also supports OAuth for Claude custom connectors. In that flow, Claude sends a Duckie-issued OAuth access token instead of a static customer API key.

​
Connect from Claude

Use the MCP endpoint URL when you add Duckie as a Claude custom connector. 
https://app.useduckie.ai/api/mcp
You do not need to create a Duckie API key, OAuth client ID, or OAuth client secret for Claude. Claude discovers Duckie’s OAuth configuration from the MCP endpoint, registers itself as a public OAuth client, and redirects you to Duckie. After you sign in and approve access, Duckie issues OAuth tokens for Claude to use. 
Authorization: Bearer dk_mcp_access_...
That token is tied to the Duckie user, organization, and approved read scopes. Claude uses it to call the same MCP endpoint that direct clients can call with a customer API key.
The user who connects Claude must have permission to manage API keys in Duckie. If Claude shows optional advanced fields for OAuth Client ID or OAuth Client Secret, leave them blank unless Duckie Support has given you specific values.
Do not put a Duckie API key in the MCP URL or paste it into Claude as a static bearer token. Claude remote custom connectors use OAuth for authenticated servers.
For more detail on Claude’s connector behavior, see Claude’s custom connector setup guide and connector authentication reference.

​
Find the MCP setup panel

1

Open API Access

Go to Settings -> API Access.
2

Copy connection details

In the MCP endpoint panel, copy the endpoint URL, auth header format, or a JSON-RPC request example.
3

Test a key

Paste a customer API key into Test connection and click Test. Duckie sends an MCP initialize request to confirm the key can authenticate.
The full API key is shown only once when you create it. The MCP test field is for keys you already stored outside Duckie.

​
Initialize

Duckie currently returns MCP protocol version 2025-06-18. 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}
Successful initialization returns the duckie-customer-api server info and tool capabilities.

​
List available tools

Use tools/list to list the wrapper tools available to the customer API key or OAuth token. 
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
The response includes only tools allowed by the credential’s scopes.
ScopeTools
api:runs:readduckie_list_runs, duckie_get_run, duckie_list_run_tool_options
api:tools:readduckie_list_tools, duckie_get_tool
api:agents:readduckie_list_agents, duckie_get_agent
api:guidelines:readduckie_list_guidelines, duckie_get_guideline
api:guardrails:readduckie_list_guardrails, duckie_get_guardrail
api:runbooks:readduckie_list_runbooks, duckie_get_runbook

​
Call a tool

Use tools/call with a tool name and arguments. 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "duckie_list_runs",
    "arguments": {
      "limit": 10,
      "status": ["completed", "failed"]
    }
  }
}
Tool-call results return MCP content where the first text item contains the JSON payload from the underlying Duckie API response. 
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"data\": [],\n  \"pagination\": {\n    \"limit\": 10,\n    \"next_cursor\": null,\n    \"has_more\": false\n  }\n}"
      }
    ],
    "isError": false
  }
}

​
Arguments

MCP tool arguments match the filters and IDs used by the REST API. For example, duckie_list_runs supports pagination, run filters, duration filters, and metadata filters. duckie_get_run requires run_id. If an argument does not match the tool input schema, Duckie returns a JSON-RPC -32602 error.

Authentication

Create an API key and send it with each request.

Pagination and Filtering

See the REST filters mirrored by the MCP wrapper tools.