MCP server

​

Endpoint and transport

• URL: https://back.tilion.dev/mcp/. https://back.tilion.dev/mcp answers 307 to the slash form, so configure the slash form.
• Transport: streamable HTTP, stateless. Each JSON-RPC message is a POST /mcp/ with Content-Type: application/json and an Accept header listing both application/json and text/event-stream. Without both, the server answers 406 with a JSON-RPC error (Not Acceptable: Client must accept both application/json and text/event-stream).
• Responses are server-sent events: one event: message with the JSON-RPC result in data. A notification answers 202 with no body.
• GET /mcp/ answers 405 with Allow: POST, DELETE and no body: there is no server push stream to open.
• The first request is answered with an Mcp-Session-Id header. Send it back on every later request; it is the id of your conversation, and it keeps your browser handle separate from other clients on the same account.
• The server keeps the link between your conversation and its browser for 15 minutes between tool calls. After that, or once the session itself idles out, a tool answers ok: false with expired: true and asks you to call create_browser_session again.

​

Authentication

HTTP/1.1 401
WWW-Authenticate: Bearer resource_metadata="https://back.tilion.dev/.well-known/oauth-protected-resource"

{"error": "unauthorized: send Authorization: Bearer <tilion api key>"}

​

Initialize

curl -X POST https://back.tilion.dev/mcp/ \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",
       "params": {"protocolVersion": "2025-03-26", "capabilities": {},
                  "clientInfo": {"name": "my-client", "version": "0.1"}}}'

HTTP/1.1 200
Content-Type: text/event-stream
Mcp-Session-Id: 787b5fca95774bff8e479729f1e189d8

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"Tilion Cloud Browser","version":"..."},"instructions":"Tilion gives you a real browser running in the cloud. ..."}}

​

Tools

​

OAuth

curl https://back.tilion.dev/.well-known/oauth-authorization-server

{
  "issuer": "https://back.tilion.dev",
  "registration_endpoint": "https://back.tilion.dev/oauth/register",
  "authorization_endpoint": "https://back.tilion.dev/oauth/authorize",
  "token_endpoint": "https://back.tilion.dev/oauth/token",
  "scopes_supported": ["cdp"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "none"],
  "code_challenge_methods_supported": ["S256"]
}

curl https://back.tilion.dev/.well-known/oauth-protected-resource

{
  "resource": "https://back.tilion.dev/mcp",
  "authorization_servers": ["https://back.tilion.dev"],
  "scopes_supported": ["cdp"],
  "bearer_methods_supported": ["header"]
}

1. POST /oauth/register with {"redirect_uris": [...], "client_name": "...", "token_endpoint_auth_method": "none" | "client_secret_post"}. Answers 201 with client_id, the registered URIs, grant_types and response_types, plus client_secret once for a confidential client. Redirect URIs must be https, or http on localhost, 127.0.0.1 or [::1], with no fragment; anything else answers 400. Registration is unauthenticated and throttled per address.
2. GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256&scope=cdp. PKCE with S256 is mandatory and cdp is the only scope. An unknown client or an unregistered redirect URI stops on an error page; other mistakes bounce to the redirect URI with error and error_description. A valid request sends the user to a consent page on the same host where they sign in with an emailed code and approve what the client gets: open and control a browser in their account, read what it visits, and spend their credits.
3. The client is redirected back with code and state.
4. POST /oauth/token as a form with grant_type=authorization_code, code, code_verifier, redirect_uri, client_id and, for a confidential client, client_secret. Codes are single use and bound to the client and redirect URI. The answer carries an access token (mcpt_...) and a refresh token; grant_type=refresh_token rotates them, and a refresh token is single use. Errors are 400 or 401 with error and error_description in the OAuth vocabulary (invalid_client, invalid_grant, unsupported_grant_type).
5. The access token goes in Authorization: Bearer mcpt_... on /mcp/ and on the REST API, where it carries the cdp scope. Revoke it from API keys in the dashboard.

​

Client configuration

claude mcp add --transport http tilion https://back.tilion.dev/mcp/ \
  --header "Authorization: Bearer ph_live_..."

{
  "mcpServers": {
    "tilion": {
      "url": "https://back.tilion.dev/mcp/",
      "headers": {"Authorization": "Bearer ph_live_..."}
    }
  }
}