# MCP Integration

Chaser exposes an MCP-compatible JSON-RPC endpoint for AI agent integration. Use it to give agents access to sandbox environments, browser automation, and workspace management through a standard tool interface.

## Endpoint

```
POST /v1/mcp
Authorization: Bearer <api_key>
Content-Type: application/json
```

Both user API keys and service account API keys can authenticate to this endpoint.

## Local stdio bridge

If your agent expects a local stdio MCP server, use the CLI bridge:

```bash
# install binary (either path works)
npm i -g chaser-cli
# or
npx chaser-mcp --help

# keep auth in env (not in agent config files)
export CHASER_API_KEY=\"sk_your_key_here\"
export CHASER_API_URL=\"https://api.chaser.sh\"

# run bridge directly
chaser mcp serve
```

Install config entries for supported agents:

```bash
chaser mcp install --agent all
chaser mcp doctor --agent all
```

## Supported methods

| Method | Description |
|--------|-------------|
| `initialize` | Initialize the MCP session |
| `ping` | Health check |
| `notifications/initialized` | Client initialization notification |
| `tools/list` | List available tools |
| `tools/call` | Call a tool |

## High-level tools

These are the recommended starting points for agent integration:

### `terminal`

Run shell commands and perform structured file operations in a sandbox. Auto-provisions or reuses a session when `session_id` is omitted.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `session_id` | string | Target a specific session (optional) |
| `workspace` | string | Workspace name or ID (optional) |
| `ephemeral` | boolean | Use a disposable session (optional) |
| `image` | string | OCI image for ephemeral sandboxes (optional) |
| `command` / `cmd` | string | Shell command to run |
| `xml` | string | Structured file operation (`read_file`, `write_file`, `apply_edit`, `list_files`) |
| `timeout_ms` | number | Execution timeout in milliseconds |

```bash
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "terminal",
      "arguments": {
        "workspace": "my-project",
        "command": "git status && ls /workspace"
      }
    }
  }' | jq
```

### `browser`

Browser automation backed by an auto-provisioned or reused browser session, driven through `chrome-devtools-mcp`.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `session_id` | string | Target a specific session (optional) |
| `workspace` | string | Workspace name or ID (optional) |
| `ephemeral` | boolean | Use a disposable session (optional) |
| `action` | string | `prepare`, `discover`, or `call` |
| `method` | string | Browser tool method name (required for `action=call`) |
| `params` | object | Arguments for the browser tool (for `action=call`) |
| `timeout_ms` | number | Execution timeout in milliseconds |

```bash
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "browser",
      "arguments": {"ephemeral": true, "action": "prepare"}
    }
  }' | jq
```

## Lifecycle and utility tools

For explicit control over sessions and workspaces:

| Tool | Description |
|------|-------------|
| `chaser_list_sessions` | List sessions in the active account |
| `chaser_get_session` | Get session details by ID |
| `chaser_create_browser_session` | Create a browser session |
| `chaser_create_sandbox_session` | Create a sandbox session |
| `chaser_terminate_session` | Terminate a session |
| `chaser_exec_sandbox` | Execute a command in a sandbox |
| `chaser_self_test_sandbox` | Run runtime diagnostics |
| `chaser_get_sandbox_forward_url` | Get a port forwarding URL |
| `chaser_list_workspaces` | List workspaces |
| `chaser_get_workspace` | Get workspace details |
| `chaser_delete_workspace` | Delete a workspace |
| `chaser_bulk_delete_workspaces` | Bulk delete workspaces |
| `chaser_set_workspace_name` | Rename a workspace |

## User-only tools

These tools are available only to human user principals (not service accounts):

| Tool | Description |
|------|-------------|
| `chaser_request_assistant_config_change` | Propose an assistant config change |
| `vault_set` | Store a credential in the vault |
| `vault_delete` | Remove a credential |
| `vault_list_keys` | List vault credential keys |

## Dynamic MCP tools

Workspace-defined MCP servers can expose additional tools:

| Tool | Description |
|------|-------------|
| `mcp_call` | Call a workspace-defined MCP tool |
| `mcp_discover` | Discover tools from a workspace MCP server |

The `assistant_id` parameter on `mcp_call`/`mcp_discover` is only supported for user principals (for assistant-scoped vault injection).

## Compatibility

`chaser_sa3p_execute` is still accepted for backward compatibility but new integrations should use `terminal`.

## Service account access

Service account API keys receive the account-scoped infrastructure tool catalog. They can use `terminal`, `browser`, all lifecycle/utility tools, and `mcp_call`/`mcp_discover`. They cannot access assistant config-change or vault tools.

## CHASM

CHASM assistants use this same MCP surface internally. Chaser handles authentication on behalf of signed-in product users, so assistants do not need a separate API key.

## List available tools

```bash
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | jq
```