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

# Connectors & MCP

> Securely extend AI assistants with your Coconut instances using the Model Context Protocol

## Why connectors and MCP matter

The **Model Context Protocol (MCP)** is an open standard that lets AI assistants — like Claude, ChatGPT, Cursor, and others — securely talk to external systems through a common interface. A **connector** is simply an MCP server that exposes a specific product or service (in our case, Coconut) as a set of tools the AI can call on your behalf.

Instead of copy‑pasting between tools or building bespoke integrations, connectors give your AI assistant real, live access to the systems where your work actually lives, while preserving the permissions of the signed‑in user. If you can't see something in the source system, the connector can't reach it either.

Key benefits:

* **Live context** — the assistant reads current state (tasks, jobs, knowledge) instead of stale snapshots.
* **Actionable** — beyond reading, it can create and update records on your behalf.
* **Permission‑aware** — every request runs as you, subject to your Coconut scopes and role.
* **Portable** — any MCP‑compatible client works the same way (Claude, Cursor, Windsurf, ChatGPT, custom agents, etc.).

## The Coconut connector

The Coconut connector is an MCP server hosted at:

```
https://app.coconut.dev/mcp
```

Once connected, your AI assistant can reach across every Coconut instance you have access to — listing instances, inspecting their health, reading and writing tasks and knowledge, pulling context, and browsing jobs — all with per‑scope authorization.

### What it can access

The Coconut MCP server exposes the following tools. Each tool is gated by a specific OAuth scope, so you can grant read‑only access or allow writes on a per‑capability basis.

| Tool                      | Description                                                                                     | Required scope    |
| ------------------------- | ----------------------------------------------------------------------------------------------- | ----------------- |
| `coconuts_list`           | List Coconut instances visible to the signed‑in user or active organization.                    | `coconuts:read`   |
| `coconuts_health_list`    | Get health and latency for eligible Coconut instances.                                          | `health:read`     |
| `tasks_list`              | List tasks for one Coconut, optionally filtered.                                                | `tasks:read`      |
| `tasks_get`               | Get one task from a Coconut.                                                                    | `tasks:read`      |
| `tasks_create`            | Create a task on a Coconut you can modify.                                                      | `tasks:write`     |
| `task_update`             | Update an existing task on a Coconut. Only provided fields are changed.                         | `tasks:write`     |
| `task_comment`            | Add a comment to an existing task.                                                              | `tasks:write`     |
| `task_review`             | Start a non‑interactive agent review session for an existing task. Uses `prepare-task` context. | `tasks:write`     |
| `task_start`              | Start a non‑interactive agent work session for an existing task. Uses `change-task` context.    | `tasks:write`     |
| `knowledge_search`        | Search knowledge documents on a Coconut.                                                        | `knowledge:read`  |
| `knowledge_get`           | Get a knowledge document by filename or path.                                                   | `knowledge:read`  |
| `knowledge_create`        | Create a knowledge document on a Coconut you can modify.                                        | `knowledge:write` |
| `knowledge_update`        | Update an existing knowledge document.                                                          | `knowledge:write` |
| `context_get`             | Get one or more context documents (role, agents, team, memory).                                 | `context:read`    |
| `jobs_list`               | List jobs for one Coconut.                                                                      | `jobs:read`       |
| `jobs_get`                | Get one job definition from a Coconut.                                                          | `jobs:read`       |
| `job_create`              | Create a scheduled job on a Coconut you can modify. Provide an interval schedule object.        | `jobs:write`      |
| `job_update`              | Update an existing scheduled job on a Coconut. Only provided fields are changed.                | `jobs:write`      |
| `job_run`                 | Manually trigger a one-time run for an existing job.                                            | `jobs:write`      |
| `connectors_catalog_list` | List available connectors in the Coconut Dashboard catalog.                                     | `connectors:read` |
| `skills_list`             | List skills on an organization Coconut.                                                         | `skills:read`     |
| `skills_get`              | Get a skill by identifier from an organization Coconut.                                         | `skills:read`     |
| `skills_create`           | Create a new skill on an organization Coconut.                                                  | `skills:write`    |
| `skills_update`           | Update an existing skill on an organization Coconut.                                            | `skills:write`    |
| `skills_delete`           | Delete a skill from an organization Coconut.                                                    | `skills:write`    |

<Tip>
  To call these Coconut MCP tools from the CLI, use [`nut coconut`](/cli/coconut). Prefer typed wrappers like `nut coconut task list --name <name>`, `nut coconut skill list --name <name>`, and `nut coconut job list --name <name>` when available. Use `nut coconut call <tool_name>` as the raw escape hatch for newly added tools.
</Tip>

<Tip>
  Scopes are requested during the initial OAuth flow. You can re‑authenticate at any time to broaden or narrow the tools your assistant can invoke.
</Tip>

<Note>
  `task_review` and `task_start` will not start a new agent session if the task status is already `active`. In that case the tool returns a message indicating the task is already active and no new session was started.
</Note>

<Note>
  `skills_create`, `skills_update`, and `skills_delete` are admin-only write capabilities for skill management. They are only exposed to Clerk organization admins and only apply to org-owned coconuts in the user's active organization context.
</Note>

## Add the Coconut connector to Claude

Claude supports remote MCP servers as **custom connectors**. The steps below are adapted from [Anthropic's official guide](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities).

<Note>
  Custom connectors are available on Claude, Cowork, and Claude Desktop for users on Free, Pro, Max, Team, and Enterprise plans. Free users are limited to one custom connector. On Team and Enterprise plans, an Owner or Primary Owner must enable the connector for the organization first.
</Note>

<Steps>
  <Step title="Open connector settings">
    In Claude, navigate to **Customize → Connectors**. Click the **+** button next to **Connectors**.
  </Step>

  <Step title="Add a custom connector">
    Select **Add custom connector**.
  </Step>

  <Step title="Enter the Coconut MCP details">
    Use the following values:

    * **Name:** `Coconut`
    * **URL:** `https://app.coconut.dev/mcp`

    Leave advanced settings (OAuth Client ID and secret) empty unless your organization requires them.
  </Step>

  <Step title="Connect and authenticate">
    Click **Add**, then follow the OAuth prompts to sign in to Coconut and grant the scopes you want the assistant to use (for example, `tasks:read`, `knowledge:write`).
  </Step>

  <Step title="Enable it in a conversation">
    In any chat, click the **+** button (or type `/`), hover over **Connectors**, and toggle **Coconut** on. Claude can now call Coconut tools whenever it's useful — e.g. "List open tasks on my main Coconut" or "Create a task titled 'Audit login flow' on coconut `acme-prod`."
  </Step>
</Steps>

<Tip>
  You can also open the ready‑made setup URL directly: [https://app.coconut.dev/connectors/coconut](https://app.coconut.dev/connectors/coconut).
</Tip>

## Other MCP clients

Because the Coconut connector is a standard remote MCP server, any MCP‑capable client works the same way. Point your client at:

```
https://app.coconut.dev/mcp
```

…and complete the OAuth flow. See our guides for [Cursor](/ai-tools/cursor), [Windsurf](/ai-tools/windsurf), and [Claude Code](/ai-tools/claude-code) for client‑specific setup details.

## Security and permissions

* All traffic to `https://app.coconut.dev/mcp` is encrypted in transit.
* The connector never escalates privileges — tool calls execute as the authenticated user, subject to your Coconut role and scopes.
* You can disconnect the connector at any time from your AI client's connector settings, which revokes its ability to call Coconut tools.
* On Team and Enterprise Claude plans, Owners can restrict write‑scoped tools (e.g. allow `tasks:read` while blocking `tasks:write`) org‑wide.

## References

* [Coconut MCP endpoint](https://app.coconut.dev/mcp)
* [Anthropic: Use connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities)
* [Model Context Protocol](https://modelcontextprotocol.io)