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

# MCP server

> Connect Adapt to external agents and tools through a hosted Model Context Protocol endpoint.

<Note>
  The MCP server is in beta. The interface may still change.
</Note>

Adapt hosts a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so external agents and tools can talk to your organization programmatically — not just through Slack and the web app. Point an MCP-capable client at Adapt, and it can run a full agent with all of your knowledge, integrations, and skills behind it.

export const AGENT_PROMPT = `Help me connect Adapt to you over MCP and run my first query.

Adapt is an AI agent with my company's knowledge, integrations, and skills behind it. It hosts a Model Context Protocol (MCP) server so any MCP client can run a full Adapt agent in my organization - from my editor or terminal, not just Slack or the web app. The server is one hosted endpoint, https://app.adapt.com/mcp (Streamable HTTP), and it authenticates with OAuth: you discover the authorization server from the endpoint and I approve the sign-in in my browser. There is no token for me to paste. It exposes one tool, ask_adapt, which runs an agent and returns the reply.

Walk me through it:

1. Add the server using whatever fits the client I'm in:
   - Claude Code: claude mcp add --transport http adapt https://app.adapt.com/mcp
   - Codex: codex mcp add adapt --url https://app.adapt.com/mcp
   - Cursor: add {"mcpServers":{"adapt":{"url":"https://app.adapt.com/mcp"}}} to ~/.cursor/mcp.json, then Settings -> MCP -> Login
   - VS Code: add {"servers":{"adapt":{"type":"http","url":"https://app.adapt.com/mcp"}}} to .vscode/mcp.json
   - Any other client: register it as a remote Streamable HTTP server at that URL and let it run the OAuth flow.

2. Complete the OAuth sign-in in the browser window that opens. In Claude Code, run /mcp and pick Adapt if the prompt does not appear on its own. In Codex, run codex mcp login adapt if it does not start automatically. Wait for me to confirm I finished signing in before continuing.

3. Most MCP clients only load servers at startup, so I may need to restart the client or open a new chat before the Adapt tools appear. Tell me if that's needed and wait for me to do it.

4. Once ask_adapt is available, help me run a first query end to end and confirm I get a reply.

Docs: https://adapt.com/docs/platform/mcp-server`;

## Endpoint

```
https://app.adapt.com/mcp
```

Streamable HTTP, authenticated with OAuth. There is no token to copy: your client discovers Adapt's authorization server from the endpoint and opens a browser window for you to approve. Your organization comes from the token, so multi-org accounts need no extra header — sign in with the organization you want to work in.

## Client setup

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http adapt https://app.adapt.com/mcp
    ```

    Start Claude Code and run `/mcp`, then choose Adapt to sign in. Use `/mcp` any time to check status or re-authenticate.
  </Tab>

  <Tab title="Codex CLI">
    **Available in every project**

    ```bash theme={null}
    codex mcp add adapt --url https://app.adapt.com/mcp
    codex mcp login adapt
    ```

    `codex mcp add` detects that Adapt supports OAuth and usually starts the browser flow on its own; `codex mcp login` is there for when it doesn't. The server is written to `~/.codex/config.toml`.

    **This project only**

    Create `.codex/config.toml` in a trusted repository:

    ```toml theme={null}
    [mcp_servers.adapt]
    url = "https://app.adapt.com/mcp"
    ```

    Then, from the repository root:

    ```bash theme={null}
    codex mcp login adapt
    ```

    Verify and restart:

    ```bash theme={null}
    codex mcp get adapt
    codex mcp list
    ```

    Codex reads config at launch, so restart it after authenticating. Inside a session, `/mcp` lists the server and its `ask_adapt` tool.

    <Note>
      Don't put credentials in `.codex/config.toml` — Codex stores OAuth tokens separately. And avoid defining `adapt` at both user and project scope unless you specifically want the project one to win.
    </Note>
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

    ```json theme={null}
    {
      "mcpServers": {
        "adapt": {
          "url": "https://app.adapt.com/mcp"
        }
      }
    }
    ```

    Open **Settings** > **MCP**, click **Login** next to Adapt, and complete the browser flow.
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "adapt": {
          "type": "http",
          "url": "https://app.adapt.com/mcp"
        }
      }
    }
    ```

    Start the server from the `mcp.json` editor, or run **MCP: List Servers** from the Command Palette, then complete the browser flow.
  </Tab>

  <Tab title="Claude Desktop">
    Go to **Settings** > **Connectors** > **Add custom connector**. Name it `Adapt`, enter the endpoint, then choose **Add** > **Connect** and complete the browser flow.

    ```
    https://app.adapt.com/mcp
    ```
  </Tab>
</Tabs>

### Other clients

<AccordionGroup>
  <Accordion title="ChatGPT">
    Go to **Settings** > **Connectors** > **Add custom connector** (you may need to enable developer mode). Name it `Adapt`, use the endpoint below, and complete the browser flow.

    ```
    https://app.adapt.com/mcp
    ```

    Custom connectors are available on ChatGPT Pro, Business, and Enterprise.
  </Accordion>

  <Accordion title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`, then reload the MCP server list and complete the browser flow.

    ```json theme={null}
    {
      "mcpServers": {
        "adapt": {
          "serverUrl": "https://app.adapt.com/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Zed">
    Add to Zed's `settings.json`, or use **Settings** > **AI** > **MCP Servers** > **Add Server** > **Add Remote Server**. Complete the browser flow when prompted.

    ```json theme={null}
    {
      "context_servers": {
        "adapt": {
          "source": "http",
          "enabled": true,
          "url": "https://app.adapt.com/mcp"
        }
      }
    }
    ```

    A remote server with no `Authorization` header makes Zed run the standard MCP OAuth flow.
  </Accordion>

  <Accordion title="Goose">
    Run `goose configure`, choose **Add Extension** > **Remote Extension (Streaming HTTP)**, enter the endpoint, and complete the browser flow.

    ```
    https://app.adapt.com/mcp
    ```
  </Accordion>

  <Accordion title="OpenCode">
    Add to `opencode.json`:

    ```json theme={null}
    {
      "mcp": {
        "adapt": {
          "type": "remote",
          "url": "https://app.adapt.com/mcp",
          "enabled": true
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Factory">
    Add to `~/.factory/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "adapt": {
          "type": "http",
          "url": "https://app.adapt.com/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Any other MCP client">
    Configure a remote Streamable HTTP server pointing at the endpoint below. Clients that support OAuth discovery will find Adapt's authorization server from it and open the consent flow.

    ```
    https://app.adapt.com/mcp
    ```
  </Accordion>
</AccordionGroup>

## Teach your agent

Rather have your agent do it? Copy this prompt and paste it into Claude Code, Codex, Cursor, or any other MCP client — it will walk you through the setup above and run your first query.

<button
  onClick={(e) => {
navigator.clipboard.writeText(AGENT_PROMPT);
const label = e.currentTarget.querySelector("[data-label]");
if (!label) return;
const original = label.textContent;
label.textContent = "Copied!";
setTimeout(() => { label.textContent = original; }, 2000);
}}
  className="inline-flex items-center gap-2 rounded-lg border border-gray-200 bg-gray-50 px-4 py-2 text-sm font-semibold text-gray-800 no-underline cursor-pointer transition-colors hover:bg-gray-100 hover:border-gray-300 dark:border-white/10 dark:bg-white/5 dark:text-gray-100 dark:hover:bg-white/10"
>
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
    <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

    <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
  </svg>

  <span data-label>Copy prompt</span>
</button>

## What you can do

Once connected, you can address Adapt with `@adapt` from your client and put the same agent that runs in Slack and the web app to work — now alongside whatever you're already doing in your editor or terminal. A few examples:

**Use your integrations**

```
@adapt close out ENG-1234 now that the fix is merged and deployed
```

```
@adapt pull up ENG-1234, walk me through the likely root cause, then let's work the fix together
```

**Draw on company knowledge**

```
@adapt re-read the engineering style guide in company knowledge and apply it to the changes on this branch
```

```
@adapt you're over-commenting the code. Update our knowledge so we only annotate genuinely unclear logic, and when something needs a comment to be understood, weigh whether it should be rewritten instead
```

**Use apps and the sandbox**

```
@adapt spin up a minimal app that demos this code so I can share it with my team
```

**Load up Claude or Codex with full context from an Adapt chat**

```
hey claude, start working through this Adapt chat using the MCP, I was talking with the team and Adapt in Slack and ended up with a great idea to build out.
```

## Authentication

Adapt serves OAuth protected-resource metadata at the endpoint, so MCP clients discover the authorization server and run the sign-in flow themselves.

* Your client opens a browser window the first time it connects. Approve the sign-in and you're done.
* Access tokens are short-lived (5 minutes) and your client refreshes them silently. Your session stays valid until 30 days of inactivity.
* Your organization comes from the token. Sign in with the organization you want to work in.

<Note>
  Session-token authentication, used during early access, is no longer accepted. If you connected before beta, see [Reconnecting an early-access setup](#reconnecting-an-early-access-setup).
</Note>

## The `ask_adapt` tool

The server exposes one tool, `ask_adapt`, which runs an Adapt agent in your organization.

| Parameter | Type   | Description                                                              |
| --------- | ------ | ------------------------------------------------------------------------ |
| `message` | string | The message to send to the agent. Omit to read an existing conversation. |
| `chat_id` | string | The conversation to continue or read. Omit to start a new conversation.  |

Three ways to call it:

* **Start a conversation** — pass `message` with no `chat_id`. Adapt creates a new chat, runs the agent, and returns the reply.
* **Continue a conversation** — pass both `message` and `chat_id` to keep going in the same chat.
* **Read a conversation** — pass only `chat_id` to return the full transcript.

Every reply is prefixed with `chat_id: <id>`. Save that value to continue or revisit the conversation later.

### Long-running requests

Most MCP clients time out a tool call after 60 seconds, and plenty of Adapt work takes longer. Rather than hold the connection open, `ask_adapt` hands the run back to you:

<Steps>
  <Step title="The tool waits up to 45 seconds">
    Most requests finish inside that window and return normally.
  </Step>

  <Step title="Still going? You get a handle">
    The tool returns the `chat_id` and `status: working`.
  </Step>

  <Step title="Poll that chat_id">
    Call `ask_adapt` again with only the `chat_id` — no `message` — at least 30 seconds later. Keep polling until the response no longer says `working`.
  </Step>
</Steps>

Don't resend the original message while polling. The run is already in flight, and resending starts a second one.

A run that ends without producing a reply returns `status: failed` with the transcript intact.

## Permissions

The agent acts as you. It runs in the organization you signed in with and uses that organization's integrations, knowledge, and skills, under your membership.

Anything your organization restricts through [policies](/docs/features/policies) applies to MCP the same way it applies in Slack and the web app — connecting over MCP does not widen what you can reach.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Adapt tools don't appear in my client">
    Most MCP clients only load servers at startup. Restart the client, or open a new chat, and check again. In Claude Code and Codex, `/mcp` lists the registered servers and their tools.
  </Accordion>

  <Accordion title="Codex: MCP startup interrupted, the following servers were not initialized">
    Run `codex mcp get adapt` from the project you expect it in. If you configured it per-project, confirm the repository is trusted — Codex only loads project config for trusted projects — or move the server to user-global config instead. Then run `codex mcp login adapt`, complete the browser flow, and restart Codex.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Your client isn't signed in, or its token expired. The response advertises where to authenticate, so most clients recover on their own. If yours doesn't, sign in again: `/mcp` in Claude Code, `codex mcp login adapt` in Codex.

    If you're still passing an `Authorization` header from an early-access setup, remove it — see below.
  </Accordion>

  <Accordion title="403 Access denied">
    Authentication worked, but the signed-in account isn't an active, email-verified member of that organization. Verify your email, or ask an admin to confirm your membership.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    The endpoint allows 300 requests per minute per IP. Polling a long-running run every 30 seconds, as instructed, stays well inside that.
  </Accordion>
</AccordionGroup>

### Reconnecting an early-access setup

Early access authenticated with your Adapt session token as a Bearer credential. Configurations that still pass that header stop working. Remove the server and add it back without the header.

Claude Code:

```bash theme={null}
claude mcp remove adapt
claude mcp add --transport http adapt https://app.adapt.com/mcp
```

Codex: delete the `http_headers` line (and the `X-Adapt-Org` header, if present) from the `[mcp_servers.adapt]` block in `~/.codex/config.toml`, leaving just the URL, then run `codex mcp login adapt`.

```toml theme={null}
[mcp_servers.adapt]
url = "https://app.adapt.com/mcp"
```

## Related

* [Web app](/docs/platform/web-app)
* [Slack app](/docs/platform/slack-app)