MCP server

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 an environment of it, point the code under test at that environment, read back what the code sent, and grade it against a test. 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

claude mcp add --transport http twinbay https://mcp.twinbay.ai/mcp

{
  "mcpServers": {
    "twinbay": {
      "url": "https://mcp.twinbay.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "twinbay": {
      "type": "http",
      "url": "https://mcp.twinbay.ai/mcp"
    }
  }
}

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, environment and test routes, generated from the OpenAPI spec, so each one behaves like the endpoint it comes from. The API Reference tab documents them.

Twins	Environments	State and logs
`list_twins`	`create_environment`, `list_environments`, `get_environment`	`list_environment_records`, `update_environment_record`
`get_twin`	`get_environment_twin`, `start_environment_twin`, `stop_environment_twin`	`advance_environment`
	`collect_environment_twin_credential`	`list_request_logs`, `get_request_log`
	`list_scenarios`, `create_scenario`, `get_scenario`, `update_scenario`, `delete_scenario`
	`create_seed`, `list_seeds`, `get_seed`, `delete_seed`	`list_seed_suggestions`

create_scenario saves a named list of twins with optional existing seed IDs without starting an environment. update_scenario accepts a name, a replacement twin list, or both. Pass its ID as scenario to create_environment, or set save_as_scenario when creating an environment from a twin list. These tools use the same organization and seed checks as the API.

Tests	Evaluators	Runs	Evaluations
`create_test`, `list_tests`, `get_test`, `update_test`	`create_evaluator`, `list_evaluators`, `get_evaluator`	`create_test_run`	`create_evaluation`, `list_evaluations`, `get_evaluation`
`list_test_versions`, `get_test_version`		`list_test_runs`, `get_test_run`	`download_evaluation_input`

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

What an agent does with them

list_twins
create_seed             a described starting state, expanded once by a worker
create_environment      a name, and either twins or a saved scenario
get_environment_twin    wait_for=ready, then take its url
collect_environment_twin_credential
advance_environment     settle deliveries or move a workflow forward
list_request_logs   assert on the requests the code sent

To grade a run against outcomes instead of asserting on logs by hand:

create_test             a task and its outcomes; version 1 is immutable
update_test             revise the definition by appending an immutable version
create_evaluator        test_id and twins=["stripe"]; optionally pin test_version;
                        then poll get_evaluator until ready or error
create_test_run         environment_id and evaluator_id
                        (only traffic from now on counts; one open run per environment)
create_evaluation       test_run_id; phase=checkpoint keeps the run open, phase=final closes it;
                        pass an Idempotency-Key so a retry returns the same evaluation
get_evaluation          poll until completed or error, then read verdict, coverage_status and evidence
create_evaluation       pass another ready evaluator_id to regrade the same capture
download_evaluation_input   a signed link to that capture

A completed evaluation is not a passing one. Only verdict: passed is; failed, inconclusive and error are not, and an incomplete or unknown coverage_status means the capture may be missing calls. One habit keeps an agent out of trouble: read a not modelled refusal as the edge of a twin rather than as a bug to work around.

Prefer a key

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

Getting Started

Concepts

Interfaces

Request a twin

Connect

Tools

What an agent does with them

Prefer a key

​Connect

​Tools

​What an agent does with them

​Prefer a key

Connect

Tools

What an agent does with them

Prefer a key