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

# MCP

> Give your LLM of choice access to the contents of your Pond.

<Warning>
  Experimental; the MCP is new, and you may run into hiccups while using it.
</Warning>

The Pond MCP server gives your LLM of choice access to the contents of your Pond library — Threads, Fragments, suggestions, connections, and more.

This means you can use your Pond as context when working in supported AI clients.

<Note>
  During the beta, only **Claude**, **ChatGPT**, and **Codex** clients are approved to connect. Other MCP clients can start the flow but won't be able to complete authorisation yet.
</Note>

## The endpoint

Pond runs a **remote** MCP server over Streamable HTTP. There's nothing to install and run yourself — you just point your client at:

```text theme={null}
https://api.pond.li/mcp
```

<Note>
  You never paste API keys or database tokens into your client. Access is granted through Pond's OAuth flow, and every tool call is scoped to your account with the same row-level security as the app.
</Note>

## What you need

* A Pond account
* MCP beta access on that account
* An MCP client that supports remote servers with OAuth

## Connecting a client

When you add the server, your client opens Pond's OAuth flow in the browser. Sign in to Pond if needed, review the requested access, and approve it — your client then receives a token scoped to your account.

<Tabs>
  <Tab title="Claude Code">
    Add the server from your terminal:

    ```bash theme={null}
    claude mcp add --transport http pond https://api.pond.li/mcp
    ```

    The first time a tool is used, Claude Code will prompt you to authenticate in the browser. You can confirm the connection at any time with `/mcp`.
  </Tab>

  <Tab title="Claude Desktop">
    Go to **Settings → Connectors → Add custom connector**, then enter:

    * **Name:** `Pond`
    * **URL:** `https://api.pond.li/mcp`

    Claude Desktop opens Pond's sign-in to authorize access.
  </Tab>

  <Tab title="ChatGPT">
    In **Settings → Connectors**, add a custom connector pointing to:

    ```text theme={null}
    https://api.pond.li/mcp
    ```

    ChatGPT opens Pond's sign-in to authorize access.
  </Tab>

  <Tab title="Codex">
    Add Pond as a remote MCP server in your Codex config:

    ```toml theme={null}
    [mcp_servers.pond]
    url = "https://api.pond.li/mcp"
    ```

    On first use, Codex launches Pond's OAuth flow to authorize access.
  </Tab>
</Tabs>

## Permissions

When you connect, you grant one or more scopes:

* **Read** — read Threads, search your library, fetch excerpts, and find similar excerpts.
* **Write** — create Threads, attach excerpts, write Notes, and create Moves.
* **Import** — add a URL to your Pond as an Artefact.

A client only ever receives the scopes you approve.

## Available tools

<AccordionGroup>
  <Accordion title="Read">
    * `list_threads` — list your Threads
    * `get_thread` — retrieve a Thread with its excerpts and optional graph context
    * `search_library` — search excerpts, Artefacts, and Threads
    * `get_excerpt` — fetch one excerpt by ID
    * `get_excerpts_batch` — fetch multiple excerpts by ID
    * `get_excerpts_by_artefact` — fetch excerpts for an Artefact by ID or exact name
    * `get_similar_excerpts` — find excerpts similar to an existing one
  </Accordion>

  <Accordion title="Write">
    * `create_thread` — create a Thread, optionally with initial excerpts
    * `add_excerpt_to_thread` — attach an excerpt to a Thread
    * `create_note_collection` — write a Note in a Thread's notebook
    * `create_move` — create a typed semantic relationship between entities
  </Accordion>

  <Accordion title="Import">
    * `add_to_pond` — import a URL as a Pond Artefact
  </Accordion>
</AccordionGroup>

## Try it

Once connected, you can converse with your client with the context and structure of Pond threads guiding the discourse.