MCP Server

Inspect and debug Passage sessions from Claude Code, Claude Desktop, or any MCP-compatible client.

Overview

The Passage MCP server exposes session data as Model Context Protocol tools. It provides the same data available in the web dashboard — timeline, commands, network, console, logs, client connections, state transitions, and page captures (snapshots + screenshots) — formatted for LLM consumption. It can also create recording sessions for free-browse capture without an automation backend.


Claude Code / Desktop
  └─ mcp-remote (local proxy)
       └─→ MCP Server (mcp.getpassage.ai)
             └─→ Connect Service (internal)
                   └─→ Session Service (DO state + events)

Authentication

The MCP server uses bearer token authentication. Obtain a token from your Passage account and pass it via the Authorization header.

Setup

Claude Code

Add to your Claude Code MCP configuration (.claude/settings.json or project settings):


{
  "mcpServers": {
    "passage-sessions": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.getpassage.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):


{
  "mcpServers": {
    "passage-sessions": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.getpassage.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

MCP Inspector

For testing, use the MCP Inspector:


npx @modelcontextprotocol/inspector

Connect to https://mcp.getpassage.ai/mcp with the Authorization: Bearer YOUR_TOKEN header.

Tools

list_sessions

List recent sessions with status, provider, and session history.

Parameter	Type	Description
`limit`	number (optional)	Max sessions to return. Default: 20

get_session_overview

Get a session’s current state: phase, connections, link info, errors, and captured data.

Parameter	Type	Description
`session_id`	string	Session ID

get_session_timeline

Get the chronological event stream for a session.

Parameter	Type	Description
`session_id`	string	Session ID
`type_filter`	string (optional)	Comma-separated event types (e.g. `command,yield,phase_transition`)
`limit`	number (optional)	Max events to return. Default: 100

get_session_commands

Get browser commands sent during the session with their results, timing, and status.

Parameter	Type	Description
`session_id`	string	Session ID

get_session_network

Get HTTP requests and responses captured from the webview.

Parameter	Type	Description
`session_id`	string	Session ID
`url_filter`	string (optional)	Regex pattern to filter URLs
`limit`	number (optional)	Max entries to return. Default: 50

get_session_console

Get browser console entries from the webview.

Parameter	Type	Description
`session_id`	string	Session ID
`level_filter`	string (optional)	Comma-separated levels (e.g. `error,warn`)
`limit`	number (optional)	Max entries to return. Default: 100

get_session_logs

Get server protocol logs and/or client SDK logs.

Parameter	Type	Description
`session_id`	string	Session ID
`source`	`server` \| `sdk` \| `all` (optional)	Log source filter. Default: `all`

get_session_clients

Get client connection history including platform, SDK version, and timing.

Parameter	Type	Description
`session_id`	string	Session ID

get_session_state_history

Get phase transitions and, for automation sessions, derived automation stages.

Parameter	Type	Description
`session_id`	string	Session ID

get_session_captures

List page snapshots and screenshots captured during the session. Shows the preceding command context for each capture.

Parameter	Type	Description
`session_id`	string	Session ID
`type_filter`	`snapshot` \| `screenshot` (optional)	Filter by capture type
`url_filter`	string (optional)	Regex pattern to filter by page URL
`after_seq`	number (optional)	Only captures after this event sequence number
`before_seq`	number (optional)	Only captures before this event sequence number

get_capture_content

Fetch the content of a specific capture. Screenshots are returned as viewable images. Snapshots return chunked HTML — use chunk_index to paginate large pages.

Parameter	Type	Description
`session_id`	string	Session ID
`seq`	number	Capture event sequence number (from `get_session_captures`)
`chunk_index`	number (optional)	Chunk index for large HTML snapshots. Default: 0
`chunk_size`	number (optional)	Characters per chunk. Default: 50,000

get_snapshot_text

Extract visible text from an HTML snapshot (strips tags, scripts, styles). Much smaller than raw HTML — use this to see what the user saw on screen.

Parameter	Type	Description
`session_id`	string	Session ID
`seq`	number	Snapshot event sequence number

create_recording

Create a recording session for capturing user browsing. No worker (automation backend) is needed — the user browses freely and telemetry streams in. Returns session details for the user to connect via app clip or SDK.

Parameter	Type	Description
`target_url`	string (optional)	Suggested starting URL for the user
`duration_minutes`	number (optional)	Session duration in minutes (max 60). Default: 10

get_recording_summary

Get a high-level summary of a recording session: duration, pages visited, network request count, captures taken, and console errors.

Parameter	Type	Description
`session_id`	string	Session ID

Example usage

Once connected, you can ask Claude natural questions like:

“What sessions have run recently?”
“What’s happening in session sess_abc123?”
“Show me the network requests for session sess_abc123 that hit the /api/ endpoint”
“Are there any console errors in the latest session?”
“What commands were sent and did any fail?”
“Show me the screenshots from session sess_abc123”
“What text was on the page at snapshot seq 42?”
“Create a recording session so I can browse a site and capture what happens”

Claude will call the appropriate tools and interpret the results.

Next steps

Debugging — Other debugging tools (debug WebSocket, event API)
Protocol: Events — Event type reference
Concepts: Sessions — Session lifecycle