> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Endpoint

> Connect MCP clients to Duckie runs and core objects

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

```text theme={null}
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.

```http theme={null}
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.

```text theme={null}
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.

```http theme={null}
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.

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

For more detail on Claude's connector behavior, see Claude's [custom connector setup guide](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-integrations-using-remote-mcp) and [connector authentication reference](https://claude.com/docs/connectors/building/authentication).

## Find the MCP setup panel

<Steps>
  <Step title="Open API & MCP">
    Go to **Settings -> API & MCP**.
  </Step>

  <Step title="Copy connection details">
    In the **MCP endpoint** panel, copy the endpoint URL, auth header format, or a JSON-RPC request example.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  The full API key is shown only once when you create it. The MCP test field is for keys you already stored outside Duckie.
</Warning>

## Initialize

Duckie currently returns MCP protocol version `2025-06-18`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

The response includes only tools allowed by the credential's scopes.

| Scope            | Tools                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------- |
| `api:runs:read`  | `duckie_list_runs`, `duckie_get_run`, `duckie_list_run_tool_options`                  |
| `api:core:read`  | `duckie_describe_core_objects`, `duckie_list_core_objects`, `duckie_get_core_object`  |
| `api:core:write` | `duckie_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 type             | Access                                       |
| ----------------------- | -------------------------------------------- |
| `agents`                | Read/write                                   |
| `runbooks`              | Read/write                                   |
| `workflows`             | Read/write                                   |
| `snippets`              | Read/write                                   |
| `folders`               | Read/write                                   |
| `guidelines`            | Read/write                                   |
| `guideline_sections`    | Read/write                                   |
| `guardrails`            | Read/write                                   |
| `alerts`                | Read-only                                    |
| `alert_definitions`     | Read/write Agent Triggered alert definitions |
| `attributes`            | Read/write                                   |
| `attribute_options`     | Read/write                                   |
| `categories`            | Read/write                                   |
| `resolution_rules`      | Read/write                                   |
| `custom_knowledge`      | Read/write                                   |
| `knowledge_tags`        | Read/write                                   |
| `custom_tools`          | Read/write                                   |
| `deployments`           | Read-only                                    |
| `organization_overview` | Read/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:

```text theme={null}
https://app.useduckie.ai/analyze/runs?id=00000000-0000-4000-8000-000000000000
```

## Call a tool

Use `tools/call` with a tool name and arguments.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

## Related pages

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Create an API key and send it with each request.
  </Card>

  <Card title="Pagination and Filtering" icon="filter" href="/api/pagination-and-filtering">
    See the run filters mirrored by the MCP wrapper tools.
  </Card>
</CardGroup>