Squasher MCP server

The Squasher MCP server lets an AI assistant read and change your project data: issues, logs, traces, incidents, monitors, dashboards, and more. It is a hosted server at https://mcp.squasher.ai/mcp, and you sign in with your Squasher account. This server works with project data. To search these docs from an agent, use the docs MCP server instead. See Use Squasher from an AI agent.

Connect your client

To register the server with every supported agent CLI on your machine, run the installer. It shows each command and asks before it runs it.

bash <(curl -fsSL https://squasher.ai/install.sh) --mcp-only

It configures Codex CLI, Claude Code, Gemini CLI, and Amp when they are installed. For another client, add the server by hand:

Claude Code
Cursor
VS Code
Codex CLI
Other clients

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

Start claude, run /mcp, select squasher, and complete the sign-in in your browser.

Add the server to .cursor/mcp.json, or use the one-click install.

.cursor/mcp.json

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

Cursor shows a sign-in prompt for the server. Select it to sign in.

Add the server to .vscode/mcp.json, then start it from MCP: List Servers in the Command Palette.

.vscode/mcp.json

{
  "servers": {
    "squasher": { "type": "http", "url": "https://mcp.squasher.ai/mcp" }
  }
}

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

Codex opens the sign-in in your browser. Run /mcp in Codex to check the connection.

Use https://mcp.squasher.ai/mcp (Streamable HTTP). Clients that support only the older SSE transport can use https://mcp.squasher.ai/sse. For a client without OAuth, see Use an API key.

When the client connects, it opens Squasher in your browser.

Sign in to Squasher, if you are not signed in.
On Allow client to use Squasher?, check the organization and your role.
Under Access, choose what the client can do.
Select Allow.

Access	The client can
Read only	Read errors, logs, traces, monitors, incidents, releases, and settings.
Investigate	Read, run AI investigations, and request remote access. This is the default.
Full access	Also resolve and assign incidents and errors, and change configuration. Owners and admins only.
Custom	Do only the permissions that you select.

The client gets access to your current organization. Each request is limited by the access that you chose and by your role, so the assistant cannot do more than you can. Owners and admins can change project data; members can read, run investigations, and request remote access. To change the access later, revoke the app (see below) and connect it again. The access token lasts one hour, and the client refreshes it. The refresh token lasts 90 days. After that, sign in again. Squasher uses dynamic client registration and PKCE, so you do not create an OAuth app or a client secret. Clients that support MCP OAuth connect the same way, for example ChatGPT, Codex, Cursor, VS Code, OpenCode, pi, oh-my-pi, OpenClaw, and Hermes Agent. A client can ask for named scopes, for example errors:read, instead of the default mcp. Then the consent page lists only those scopes, and you can clear any of them. The scope names are the same as the API key scopes. If the organization requires SSO, sign in through its verified SSO provider before you connect the client. Existing sessions and tokens from another sign-in method need a new SSO sign-in.

Review and revoke connected apps

Account › Connected apps lists the MCP clients and Squasher CLI sign-ins that can act as you, in every organization. Each row shows the client, its access, when you connected it, and when it last renewed its token. Search by client or scope, and filter by type or access. Owners and admins also see Organization › Connected apps. It lists the connected apps of every member, and the member filter shows one person’s apps. Each revoke there is written to the organization audit log. Select Revoke on a row, or Revoke all (or Revoke shown when a filter is on). A revoked app stops working within a minute, and its saved session cannot renew. To use the app again, connect it again and choose its access. search lists only the operations that the connection can call. When a matching operation needs more access, search says how many it left out, and execute refuses the call with INSUFFICIENT_SCOPE. To get more access, connect the client again and choose more access.

Use an API key

Use an API key only for CI and headless clients that cannot open a browser. Send it on every request in the Authorization: Bearer header or the x-squasher-key header.

.mcp.json

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

The key needs read scopes. The ingest key from the Setup page has only the events:ingest scope: it sends data but cannot read it. The dashboard cannot create a key with read scopes yet, so use OAuth when your client supports it.

Two optional headers limit a session. They work with OAuth and with API keys, when your client can send custom headers:

Header	Effect
`x-squasher-project-id: <id>`	The session can use only this project. Requests for other projects fail.
`x-squasher-access-mode: read`	The session sees and runs read operations only.

Find and run operations

The server has two tools. It does not add one tool for each API endpoint, so the tool list stays small.

Tool	What it does
`search`	Finds API operations by operation ID, keyword, or a short phrase such as `open incidents`. It returns the method, path, parameters, body schema, and an example.
`execute`	Runs a short JavaScript snippet in a sandbox. The snippet calls `squasher.request({ method, path, query, body })`. The server adds your credentials. The snippet has no `fetch`, environment, or file system.

A typical call to execute after search("errors.list"):

const projectId = "YOUR_PROJECT_ID";
return await squasher.request({
  method: "GET",
  path: `/v1/projects/${projectId}/errors`,
});

Put query parameters in query. The path must not contain a query string, fragment, dot segment, backslash, or encoded path separator. execute accepts only operations that search can find. About 200 operations are available, including issues, incidents, monitors, dashboards, logs insights, traces, Web Vitals, and on-call. Key management, subscriber data, and remote-access administration are not available over MCP. The server gives each execute run up to five minutes and 100 host API calls. The returned JSON is limited to 100,000 UTF-8 bytes. If the result is larger, the response has truncated: true, the original output_bytes, a safe preview, and a hint to filter, aggregate, or page inside the sandbox. These limits belong to the server and cannot be raised by code in the request.

Writes and deletes

Every write runs through execute, so your client shows it as JavaScript. Read the snippet before you approve it. The server refuses operations that it marks as dangerous or destructive, and returns confirmation_required. These include deletes, key and secret rotation, Railway restarts and redeploys, and resource rollbacks. Do them in the dashboard or with the REST API.

Security operations

Agents can investigate security findings and prepare a response over MCP. Changes to secrets and to security policy stay with people.

Area	Agents can	Only people can
Connectors	List connectors and connections, read a connection, and plan a connection.	Connect (takes vendor secrets), test a connection (returns raw vendor records), and disconnect.
Signed webhooks	Nothing.	Create a push source and rotate its signing secret.
Detection rules	List, read, validate, and create rule packs. Turn a pack on. Start, read, and stop backtests.	Change the rules of a pack, turn a pack off, and delete a pack.
Security findings	Search entities and read their timelines. Export a finding as OCSF. Read runtime CVEs and the PII settings. List, install, and run the ready-made security queries.	Change the PII settings. Import scanner findings.
Response actions	List and read actions, read the policy, propose an action, and propose an undo.	Approve, reject, or resolve an action. Change the policy.

A proposal from an agent follows the response-action policy. An irreversible action always waits for a person. A reversible action runs at once only when an owner or admin turned on auto-run for the project. Turning a rule pack off or on is a dangerous operation, so the server returns confirmation_required until you confirm it.

Send feedback to Squasher

The feedback.submit operation sends a bug report, an idea, or a docs problem about Squasher to the Squasher team. It does not go to your project. It is a write, so a read-only session cannot run it.

return await squasher.request({
  method: "POST",
  path: "/v1/feedback",
  body: {
    kind: "bug",
    message: "What went wrong",
    context: { tool: "errors.list", client: "claude-code" },
  },
});

See Send feedback to Squasher.

Handle errors

A failed tool call returns one JSON shape. Branch on error.code, not on the message.

{
  "error": {
    "code": "RATE_LIMITED",
    "http_status": 429,
    "message": "API 429: too many requests",
    "retry_after_seconds": 7
  }
}

Code	HTTP status	Meaning
`VALIDATION`	400	The request does not match the operation schema.
`AUTH_EXPIRED`	401	Sign in again, or check the API key.
`INSUFFICIENT_SCOPE`	403	Your role, key scopes, or session limits block it.
`RESOURCE_NOT_FOUND`	404	The project or resource does not exist.
`ALREADY_DELETED`	410	The resource was deleted.
`RATE_LIMITED`	429	Wait `retry_after_seconds`, then retry.
`UPSTREAM_5XX`	5xx	Squasher had an error. Retry later.
`UPSTREAM_MALFORMED`	none	The API response was not valid JSON.
`LIMIT_EXCEEDED`	408	The run exceeded its time or host-call limit.
`UNKNOWN`	none	Any other error, including sandbox errors.

The server accepts up to 600 requests a minute from one IP address and for one credential.

Fix connection problems

The HTTP event stream can stay open while you use the tools. Keep the connection open for server notifications.

The client shows no tools. Restart the client after you add the server.
Sign-in fails or the token expired. Clear the authentication for squasher in your client and sign in again.
Invalid API key format. Squasher keys start with sq_. Check the header value.
A project is missing. The session uses the organization that was open in the dashboard when you signed in. Switch organizations in the dashboard, then sign in again from the client.

Next steps

Install agent skills

Teach your assistant the Squasher MCP and query rules.

Use Squasher from an AI agent

Compare the MCP server, the API, and the docs endpoints.

Find the right query

Ask the query guide which surface answers a question.

Browse the API

See the operations that execute can call.

Get started

Guides

Squasher MCP server

Connect your client

Review and revoke connected apps

Use an API key

Find and run operations

Writes and deletes

Security operations

Send feedback to Squasher

Handle errors

Fix connection problems

Next steps

Install agent skills

Use Squasher from an AI agent

Find the right query

Browse the API

​Connect your client

​Sign in with OAuth

​Review and revoke connected apps

​Use an API key

​Find and run operations

​Writes and deletes

​Security operations

​Send feedback to Squasher

​Handle errors

​Fix connection problems

​Next steps

Install agent skills

Use Squasher from an AI agent

Find the right query

Browse the API

Connect your client

Sign in with OAuth

Review and revoke connected apps

Use an API key

Find and run operations

Writes and deletes

Security operations

Send feedback to Squasher

Handle errors

Fix connection problems

Next steps