Get Started

Selenium integrations

Connect Selenium to your platform

Use MCP to connect your agents and display synthesis routes inside your platform. Selenium delivers the interactive viewer through the same connection. Start with the hosting example, or use the REST reference for a custom HTTP integration.

MCP + route viewer REST API OpenAPI Codex skill
MCP reference

Authentication, assessment lifecycle, retries, billing outcomes, and tool conventions.

Viewer hosting guide

Discover and embed the MCP-delivered viewer, with account and sandbox boundaries.

 Runnable MCP host example

OAuth login and refresh, Node backend, official AppBridge, and isolated viewer frames.

MCP tool schemas

Generated inputs, outputs, OAuth scopes, and viewer permissions. Discover live availability with tools/list.

OpenAPI JSON

Machine-readable API schema for custom clients and agent tool generation.

 REST reference

Quote, submit, poll, fetch routes, credits, capabilities, and errors.

 Codex skill

Drop-in skill package for agents that support Codex-style skill installation.

MCP quickstart

One connection for tools and the viewer

  1. Configure the Selenium MCP endpoint supplied for your integration. Keep the API key or OAuth token on your backend.
  2. Connect using Streamable HTTP and discover the available tools with tools/list.
  3. Read account capabilities, quote the work, and start it only after the quoted cost is authorized.
  4. Poll using the returned timing hints. Read the assessment before choosing a saved route.
  5. Call get_route_family and load its advertised UI resource through your MCP Apps host.

Already using an MCP Apps-compatible host? It can retrieve Selenium’s viewer directly. A plain MCP client needs a host bridge to render the UI; a separate React package is optional. 

Read the MCP reference and viewer hosting guide linked here:
https://b12-labs.com/docs/selenium-route-search/

Use the configured Selenium MCP connection. Discover tools, read account tiers and limits, quote before starting paid work, and retain the same quote/reference when recovering an uncertain result. Preserve the full tool result, including _meta, when rendering the viewer.

Embedded route viewer

Run the host example

Download and extract the example. With Node 22 or later, follow its README to configure your MCP endpoint, trusted OAuth issuer, and registered client. Register the local callback http://127.0.0.1:43580/oauth/callback, then run: 

npm ci --ignore-scripts
npm run build
npm start

Open the local host on loopback port 43580 and choose Connect Selenium. After provider consent, it fetches the viewer over MCP and displays it through the official AppBridge. The sandbox uses a separate origin on port 43581. The example browses existing assessments; it does not launch paid searches.

OAuth sessions and refresh tokens stay on the backend and survive a local restart. For a shared platform, bind each grant to your authenticated user and enforce narrower access rules on the backend. Opening one route does not restrict the credential’s assessment library.

Workflow

REST alternative

  1. Use the REST reference and OpenAPI schema for HTTP clients.
  2. Store the B12 API key as a secret.
  3. Call /v1/capabilities and /v1/credits.
  4. Quote with /v1/route-searches/quote.
  5. Submit with an idempotency key.
  6. Poll using retry_after_seconds.
  7. Fetch /v1/route-searches/{job_id}/routes.

Guardrails

Keep it clean

  • Never paste API keys into prompts or logs.
  • Quote before submitting paid work.
  • Use stable idempotency keys for retries.
  • Show route-family summaries, solved status, feasibility, and commercial leaves.
  • Avoid exposing internal ids unless debugging support asks for them.

REST API

Minimal request sequence

Quote

curl -X POST "$SELENIUM_API_URL/v1/route-searches/quote" \
  -H "Authorization: Bearer $B12_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"smiles":"CC(=O)Oc1ccccc1C(=O)O","tier":"standard"}'

Submit

curl -X POST "$SELENIUM_API_URL/v1/route-searches" \
  -H "Authorization: Bearer $B12_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: aspirin-standard-001" \
  -d '{"smiles":"CC(=O)Oc1ccccc1C(=O)O","name":"aspirin","tier":"standard"}'

Poll

curl "$SELENIUM_API_URL/v1/route-searches/$JOB_ID" \
  -H "Authorization: Bearer $B12_API_KEY"

Fetch routes

curl "$SELENIUM_API_URL/v1/route-searches/$JOB_ID/routes" \
  -H "Authorization: Bearer $B12_API_KEY" \
  -o selenium-routes.json