MCP

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.

Agent Skills

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

Cursor

One-click install

VS Code

One-click install

Claude Code

See instructions

Codex CLI

See instructions

Other clients

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

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:

Open the command palette and type “Cursor Settings”
Under “Tools & MCP” click “New MCP Server”
Paste the following JSON into the configuration file that opens

.cursor/mcp.json

{
  "mcpServers": {
    "squasher": {
      "url": "https://mcp.squasher.ai/mcp"
    }
  }
}

Once saved, Cursor will attempt to authenticate and show a login prompt. Select this prompt to grant Cursor access to your Squasher account.
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:

Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS)
Type “MCP: Add Server”
Choose “HTTP”
Enter the following details:
- URL: https://mcp.squasher.ai/mcp
- Name: Squasher
Click “Add”

After adding the server:

Open the Command Palette
Type “MCP: List Servers”
Select “Squasher”
Click “Start Server”
When prompted to authenticate, click “Allow”
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

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:

claude mcp add --transport http --scope user squasher https://mcp.squasher.ai/mcp

Enter Claude Code and run the /mcp slash command:

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:

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:

.mcp.json

{
  "mcpServers": {
    "squasher": {
      "type": "http",
      "url": "https://mcp.squasher.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SQUASHER_API_KEY}"
      }
    }
  }
}

Codex CLI

Ensure Codex CLI is available in your terminal

codex --version

Add the Squasher MCP server

codex mcp add squasher --url https://mcp.squasher.ai/mcp

You should be immediately prompted to authenticate. Follow the browser instructions.

Enter Codex CLI and verify

codex
/mcp

You should see:

• squasher
  • Status: enabled
  • Auth: OAuth

Gemini CLI

gemini mcp add --transport http squasher https://mcp.squasher.ai/mcp

Then authenticate:

gemini
/mcp auth squasher

Amp CLI

amp mcp add squasher https://mcp.squasher.ai/mcp

Then enter Amp CLI and follow the browser authentication prompt:

amp

Claude.ai and Claude Desktop

The Squasher MCP server can be added as a custom connector in Claude.ai and Claude Desktop.

Navigate to Settings > Connectors
Click Add custom connector
Enter the Squasher MCP server URL: https://mcp.squasher.ai/mcp
Click Add to save the connector
Follow the prompts to authenticate with your Squasher account

To use the connector in a conversation:

Click the + button in the lower left of your chat interface
Select Connectors
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 for availability.

Notion

You can access the Squasher MCP server from inside a Notion Custom Agent.

Create a new Notion Agent or open an existing one
In the Custom Agent settings, scroll to “Tools and access”
Click “Add connection”
Insert the MCP server URL: https://mcp.squasher.ai/mcp
Ensure Authentication is set to OAuth
Click “Connect”
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:

{
  "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:

AGENTS.md

## 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.

{
  "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:

Restart your client or CLI tool After installation, you may need to restart to load the new MCP configuration.
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).
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.
Verify workspace access Confirm that your Squasher account has access to the workspace and projects you expect to see.
Check API key format Squasher API keys start with sq_. If you see an “Invalid API key format” error, verify your key.

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

Agent Skills

What is the Squasher MCP server?

Quick start

Cursor

VS Code

Claude Code

Codex CLI

Other clients

Authentication

Security and credentials

Scopes and permissions

Installation instructions

Cursor

Cursor

VS Code

VS Code

Claude Code

OAuth

API key

Codex CLI

Gemini CLI

Amp CLI

Claude.ai and Claude Desktop

Notion

Other clients

Help your agent target your project

Example prompts

Available tools

Error shape

Troubleshooting

Agent Skills

​What is the Squasher MCP server?

​Quick start

Cursor

VS Code

Claude Code

Codex CLI

Other clients

​Authentication

​Security and credentials

​Scopes and permissions

​Installation instructions

​Cursor

Cursor

​VS Code

VS Code

​Claude Code

​OAuth

​API key

​Codex CLI

​Gemini CLI

​Amp CLI

​Claude.ai and Claude Desktop

​Notion

​Other clients

​Help your agent target your project

​Example prompts

​Available tools

​Error shape

​Troubleshooting

​Related docs

What is the Squasher MCP server?

Quick start

Authentication

Security and credentials

Scopes and permissions

Installation instructions

Cursor

VS Code

Claude Code

OAuth

API key

Codex CLI

Gemini CLI

Amp CLI

Claude.ai and Claude Desktop

Notion

Other clients

Help your agent target your project

Example prompts

Available tools

Error shape

Troubleshooting

Related docs