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

# Adapt MCP server and API

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

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.

## 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

> [tab] 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] 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.

> [tab] 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] 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] 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
> ```

### Other clients

> [accordion] 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] 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] 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] 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] OpenCode
>
> Add to `opencode.json`:
>
> ```json theme={null}
> {
>   "mcp": {
>     "adapt": {
>       "type": "remote",
>       "url": "https://app.adapt.com/mcp",
>       "enabled": true
>     }
>   }
> }
> ```

> [accordion] Factory
>
> Add to `~/.factory/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "adapt": {
>       "type": "http",
>       "url": "https://app.adapt.com/mcp"
>     }
>   }
> }
> ```

> [accordion] 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
> ```

## 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.

Copy prompt

## 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).

## 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:

**1. The tool waits up to 45 seconds**

Most requests finish inside that window and return normally.

**2. Still going? You get a handle**

The tool returns the `chat_id` and `status: working`.

**3. 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`.

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](https://v1-docs.adapt.com/docs/features/policies.md) 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

> [accordion] 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] 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] 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] 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] 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.

### 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](https://v1-docs.adapt.com/docs/platform/web-app.md)
* [Slack app](https://v1-docs.adapt.com/docs/platform/slack-app.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.