> ## Documentation Index > Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP > Connect Squasher to Claude Code, Cursor, VS Code, and other MCP clients over the hosted MCP endpoint. Connect Claude Code, Cursor, VS Code, and other MCP-compatible tools to your Squasher workspace so AI coding assistants can inspect errors, traces, logs, dashboards, on-call schedules, fixes, and more without custom glue code. Install Squasher Agent Skills so coding assistants know the Squasher MCP server, CLI, and query rules before they answer. ## What is the Squasher MCP server? * A hosted MCP server that accesses your Squasher workspace projects, errors, traces, metrics, dashboards, on-call schedules, notifications, and AI agent runs. * Authenticated via OAuth with the `mcp` scope, or by API key for headless clients. * Accessible from any MCP client that supports HTTP-hosted servers. ## Quick start One-click install One-click install See instructions See instructions See all options ## Authentication The hosted MCP server uses **OAuth** so you can authorize access to your Squasher workspace directly in your client. * When you connect the MCP server from your client, you're redirected to Squasher to sign in and approve MCP access. * The OAuth metadata advertises the `mcp` scope. Workspace and project permissions still determine what the connected user can read or change. * Each client registers as an OAuth application automatically via dynamic client registration. **Server URL:** ``` https://mcp.squasher.ai/mcp ``` API keys are still supported for headless clients, CI pipelines, and manual setups: ``` Authorization: Bearer sq_pk_your_api_key ``` or ``` x-squasher-key: sq_pk_your_api_key ``` ### Security and credentials * Access tokens are short-lived (15 minutes) and automatically refreshed by your MCP client. * Refresh tokens last 30 days. If a token expires, re-authenticate in your client. * Dynamic client registration uses signed JWTs — no long-lived client secrets. * OAuth uses PKCE (Proof Key for Code Exchange) to prevent authorization code interception. * All traffic to `mcp.squasher.ai` is served over HTTPS. API keys (`sq_pk_...`) provide full access to your workspace. Prefer OAuth when your MCP client supports it. Only use API keys for CI pipelines and headless environments where browser-based auth is not possible. ### Scopes and permissions OAuth grants MCP access to the connected user session. The API still enforces that user's workspace, project, and role permissions. Most MCP clients provide a way to clear authentication and re-authenticate if the user's access changes. ## Installation instructions ### Cursor Click to install the MCP server configuration for Cursor. Manual installation: 1. Open the command palette and type "Cursor Settings" 2. Under "Tools & MCP" click "New MCP Server" 3. Paste the following JSON into the configuration file that opens ```json .cursor/mcp.json theme={null} { "mcpServers": { "squasher": { "url": "https://mcp.squasher.ai/mcp" } } } ``` 4. Once saved, Cursor will attempt to authenticate and show a login prompt. Select this prompt to grant Cursor access to your Squasher account. 5. You may need to restart Cursor to load the new configuration. ### VS Code Click to install the MCP server configuration for VS Code. Manual installation: 1. Open the Command Palette (`Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS) 2. Type "MCP: Add Server" 3. Choose "HTTP" 4. Enter the following details: * URL: `https://mcp.squasher.ai/mcp` * Name: `Squasher` 5. Click "Add" After adding the server: 1. Open the Command Palette 2. Type "MCP: List Servers" 3. Select "Squasher" 4. Click "Start Server" 5. When prompted to authenticate, click "Allow" 6. Complete the Squasher sign-in flow in the browser ### Claude Code Claude Code supports two auth paths: **OAuth** (recommended for interactive use) and **API key** via a static `Authorization` header (recommended for CI and headless environments). #### OAuth ```bash theme={null} claude mcp add --transport http squasher https://mcp.squasher.ai/mcp ``` By default the server is registered for the current project only. To make it available across every project on your machine, pass `--scope user`: ```bash theme={null} claude mcp add --transport http --scope user squasher https://mcp.squasher.ai/mcp ``` Enter Claude Code and run the `/mcp` slash command: ```bash theme={null} claude ``` ``` /mcp ``` You should see the Squasher MCP server listed as needing authentication. Select it, press Enter, and follow the browser instructions to authorize. ``` ❯ squasher · △ needs authentication ``` After authenticating: ``` ❯ /mcp ⎿ Authentication successful. Connected to squasher. ``` Tokens are stored securely by Claude Code (system keychain on macOS; credentials file on Linux/Windows) and refreshed automatically. Use **Clear authentication** in the `/mcp` menu to sign out. #### API key For CI, remote agents, or any environment where a browser OAuth flow is not possible, pass your Squasher API key as a bearer header directly on `claude mcp add`: ```bash theme={null} claude mcp add --transport http squasher https://mcp.squasher.ai/mcp \ --header "Authorization: Bearer sq_pk_your_api_key" ``` Add `--scope user` to share the configuration across all your projects, or `--scope project` to commit it to `.mcp.json` for your team (use an environment variable reference like `${SQUASHER_API_KEY}` instead of inlining the key when committing). Example `.mcp.json` with environment variable expansion: ```json .mcp.json theme={null} { "mcpServers": { "squasher": { "type": "http", "url": "https://mcp.squasher.ai/mcp", "headers": { "Authorization": "Bearer ${SQUASHER_API_KEY}" } } } } ``` ### Codex CLI 1. Ensure [Codex CLI](https://developers.openai.com/codex/cli/) is available in your terminal ```bash theme={null} codex --version ``` 2. Add the Squasher MCP server ```bash theme={null} codex mcp add squasher --url https://mcp.squasher.ai/mcp ``` You should be immediately prompted to authenticate. Follow the browser instructions. 3. Enter Codex CLI and verify ```bash theme={null} codex /mcp ``` You should see: ``` • squasher • Status: enabled • Auth: OAuth ``` ### Gemini CLI ```bash theme={null} gemini mcp add --transport http squasher https://mcp.squasher.ai/mcp ``` Then authenticate: ```bash theme={null} gemini /mcp auth squasher ``` ### Amp CLI ```bash theme={null} amp mcp add squasher https://mcp.squasher.ai/mcp ``` Then enter Amp CLI and follow the browser authentication prompt: ```bash theme={null} amp ``` ### Claude.ai and Claude Desktop The Squasher MCP server can be added as a custom connector in Claude.ai and Claude Desktop. 1. Navigate to **Settings > Connectors** 2. Click **Add custom connector** 3. Enter the Squasher MCP server URL: `https://mcp.squasher.ai/mcp` 4. Click **Add** to save the connector 5. Follow the prompts to authenticate with your Squasher account To use the connector in a conversation: 1. Click the **+** button in the lower left of your chat interface 2. Select **Connectors** 3. Toggle the Squasher connector on for that conversation Custom connectors using remote MCP may not be available on all Claude plans. See [Claude's connector documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) for availability. ### Notion You can access the Squasher MCP server from inside a Notion Custom Agent. 1. Create a new Notion Agent or open an existing one 2. In the Custom Agent settings, scroll to "Tools and access" 3. Click "Add connection" 4. Insert the MCP server URL: `https://mcp.squasher.ai/mcp` 5. Ensure Authentication is set to OAuth 6. Click "Connect" 7. Complete the authentication process to give the Notion Agent access to your Squasher workspace ### Other clients For any MCP client that supports HTTP-hosted servers, use the server URL: ``` https://mcp.squasher.ai/mcp ``` Legacy SSE clients can use: ``` https://mcp.squasher.ai/sse ``` For clients that do not support OAuth, provide your API key in the headers: ```json theme={null} { "mcpServers": { "squasher": { "url": "https://mcp.squasher.ai/mcp", "headers": { "Authorization": "Bearer sq_pk_your_api_key" } } } } ``` ## Help your agent target your project By default, the MCP server may scan through all your projects to find those relevant to your query. If you are working within a project that targets a single Squasher project, include this information in your `AGENTS.md` or project context file: ```markdown AGENTS.md theme={null} ## Squasher Project - **Project ID:** `proj_abc123` - **Project Name:** `my-api` - **Environment:** `production` ``` ## Example prompts Once connected, you can ask your AI coding assistant: * "Show me the highest-volume unresolved errors in this project from the last 24 hours." * "Find logs around this stack trace and correlate them with recent traces." * "Give me the operator summary for the API service, then inspect the request latency metric." * "List the raw metrics in this project, then apply this dashboard definition." * "Inspect this dashboard widget query and tell me the top groups and peak buckets." * "Create and verify a Vercel log connector for this project." * "Show me the web vitals timeline for the last week and flag any regressions." * "Show the current on-call primary and backup, then inspect the next handoff." * "Preview a PagerDuty on-call import and show warnings before applying it." * "Review the top unresolved error and ask before creating a hosted agent run." ## Available tools The Squasher MCP is Code Mode only. Agents use `search` to discover exposed Squasher API operations, then `execute` to run small host-bound JavaScript against those operations without adding the entire API surface to the context window. | Tool | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search` | Filter exposed OpenAPI operations by keyword, operation ID, tag, path, or summary. Results include method, path, params, body schema, examples, and types. | | `execute` | Run agent-authored JavaScript against `squasher.request({ method, path, query?, body? })` in a sandbox. Auth is attached host-side. | There are no dedicated MCP tools for caller context, observability SQL, trace lookup, on-call, incident ack/resolve, deletes, log connector key rotation, hosted agent runs, or subscriptions. Use `search` to find the relevant Squasher API operation and `execute` to call exposed operations. Subscriber reads are intentionally hidden from MCP; use the API or CLI when subscriber administration is required. Because `execute` is the only MCP write path, write calls appear to MCP clients as an `execute` call containing JavaScript. Review generated code that sends `DELETE`, rotates credentials, dispatches hosted agent runs, restarts providers, redeploys providers, or changes incident state. Destructive and dangerous operations may require host approval or be rejected by the client/runtime when approval is unavailable. This keeps the tool list small regardless of how many API endpoints exist, and it makes the API spec the source of truth for agent behavior. ### Error shape Every tool error returns the same structured envelope. Agents should branch on `error.code`, not the message. ```json theme={null} { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "API 429: too many requests", "retry_after_seconds": 7, "details": { "upstream_body": "..." } } } ``` Stable codes: `VALIDATION` (400), `AUTH_EXPIRED` (401), `INSUFFICIENT_SCOPE` (403), `RESOURCE_NOT_FOUND` (404), `ALREADY_DELETED` (410), `RATE_LIMITED` (429), `UPSTREAM_5XX` (5xx), `UPSTREAM_MALFORMED` (bad JSON body), `UNKNOWN`. ## Troubleshooting If your MCP client cannot connect or tools fail to run: 1. **Restart your client or CLI tool** After installation, you may need to restart to load the new MCP configuration. 2. **Check the server URL** Make sure the MCP server URL is set to `https://mcp.squasher.ai/mcp` (streamable HTTP) or `https://mcp.squasher.ai/sse` (legacy SSE). 3. **Re-authorize the MCP server** If scopes or tokens have changed, re-authorize the Squasher MCP server in your client so it can request fresh tokens. 4. **Verify workspace access** Confirm that your Squasher account has access to the workspace and projects you expect to see. 5. **Check API key format** Squasher API keys start with `sq_`. If you see an "Invalid API key format" error, verify your key. ## Related docs * [Agent Skills](/integrations/agent-skills) * [Quickstart](/quickstart) * [Query Guide](/api-reference/query-guide) * [Dashboards as Code](/features/dashboards-as-code) * [Agent Runs](/api-reference/agent-runs) * [Vercel](/integrations/vercel)