Skip to main content
Duckie’s MCP endpoint exposes Duckie runs and core configuration objects as Model Context Protocol tools. Use it when an MCP client needs to inspect Duckie runs or read and write Duckie configuration objects without calling each 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 & MCP. 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 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 & MCP

Go to Settings -> API & MCP.
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:core:readduckie_describe_core_objects, duckie_list_core_objects, duckie_get_core_object
api:core:writeduckie_create_core_object, duckie_update_core_object, duckie_delete_core_object
The individual REST API read scopes, such as api:agents:read and api:tools:read, apply to direct /api/v1 requests. MCP uses api:runs:read for run tools and api:core:* for core object tools.

​
Core objects

Use duckie_describe_core_objects to see the currently supported object types, their readable fields, writable fields, and required create fields. Supported core object types include:
Object typeAccess
agentsRead/write
runbooksRead/write
workflowsRead/write
snippetsRead/write
foldersRead/write
guidelinesRead/write
guideline_sectionsRead/write
guardrailsRead/write
alertsRead-only
alert_definitionsRead/write Agent Triggered alert definitions
attributesRead/write
attribute_optionsRead/write
categoriesRead/write
resolution_rulesRead/write
custom_knowledgeRead/write
knowledge_tagsRead/write
custom_toolsRead/write
deploymentsRead-only
organization_overviewRead/write overview field
Core object responses include a url when Duckie can build a dashboard link for that object. Run responses also include a url, such as: 
https://app.useduckie.ai/analyze/runs?id=00000000-0000-4000-8000-000000000000

​
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. Core object tools use object_type. List calls accept limit and cursor. Get, update, and delete calls require id except for organization_overview, which can omit id because it is a singleton for the current organization. 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 run filters mirrored by the MCP wrapper tools.