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

# MCP server

> Give a coding agent the sandbox operations as tools

Twinbay runs a hosted MCP server at `https://mcp.twinbay.ai/mcp`. Add it to any MCP client and your agent can find a twin, get a sandbox of it, point the code under test at that sandbox, and read back what the code sent.

**Transport:** Streamable HTTP. **Auth:** OAuth through WorkOS AuthKit, so the client signs the user in and no API key goes into a config file.

## Connect

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http twinbay https://mcp.twinbay.ai/mcp
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "twinbay": {
        "url": "https://mcp.twinbay.ai/mcp"
      }
    }
  }
  ```

  ```json Claude Desktop theme={null}
  {
    "mcpServers": {
      "twinbay": {
        "type": "http",
        "url": "https://mcp.twinbay.ai/mcp"
      }
    }
  }
  ```
</CodeGroup>

The first call opens a browser for sign-in. After that the client holds a token bound to this server, which cannot be replayed against Twinbay's other APIs.

Any client speaking MCP can connect. Twinbay keeps no allowlist: a client publishes a Client ID Metadata Document or registers itself dynamically, and neither path needs anything from us.

## Tools

The tools are the API's own twin and sandbox routes, generated from the OpenAPI spec, so each one behaves like the endpoint it comes from. The API Reference tab documents them.

| Twins        | Sandboxes                                           | State and logs                                  |
| ------------ | --------------------------------------------------- | ----------------------------------------------- |
| `list_twins` | `create_sandbox`, `list_sandboxes`, `get_sandbox`   | `list_sandbox_records`, `update_sandbox_record` |
| `get_twin`   | `start_sandbox_twin`, `stop_sandbox_twin`           | `advance_sandbox`                               |
|              | `collect_sandbox_twin_credential`                   | `list_request_logs`, `get_request_log`          |
|              | `list_sandbox_templates`, `delete_sandbox_template` |                                                 |

Organizations, users and API keys stay out. An agent works inside the organization the signed-in member belongs to, and every tool scopes its queries the same way an HTTP request does, so it cannot read another organization's sandboxes.

## What an agent does with them

```text theme={null}
list_twins
create_sandbox      name, twins, and the state described in a sentence
get_sandbox         poll until each twin reports ready, then take its url
collect_sandbox_twin_credential
                    once per twin, so store it before moving on
advance_sandbox     settle deliveries or move a workflow forward
list_request_logs   assert on the requests the code sent
```

Two habits keep an agent out of trouble. Collect a credential once, because a second call is refused. Read a `not modelled` refusal as the [edge of a twin](/concepts#not-modelled) rather than as a bug to work around.

## Prefer a key

Scripts and CI jobs should use the [CLI](/cli) or the API with an organization API key. The MCP server exists for interactive agents, where a user signs in.