MCP Tools Reference

Every tool below is automatically scoped to the read key’s project. You don’t pass an API key per call — the bearer token from your client config provides scope.

list_projects

Returns the project the read key is scoped to. v1 read keys map 1:1 to projects, so this returns exactly one project.

Arguments: none

Example response:

{
  "data": [
    {
      "id": "70f262cd-9659-4d9d-a0b1-51b2673d821e",
      "name": "PasteCollage",
      "created_at": "2026-04-04T01:03:13.961517+00:00"
    }
  ],
  "next_cursor": null
}

get_project

Get a single project by id. Must match the read key’s scope.

Arguments:

Name	Type	Required	Notes
project_id	string	yes	Must equal the scoped project’s id.

list_logs

List logs for the scoped project, optionally filtered by level or time window.

Arguments:

Name	Type	Required	Notes
project_id	string	yes	Must equal the scoped project’s id.
level	enum	no	One of debug, info, warn, error, fatal.
since	string	no	ISO 8601 timestamp or shorthand (-15m, -24h).
until	string	no	Same format as since.
limit	int	no	1–200. Default 50.
cursor	string	no	created_at of the last row from the previous page.

Example call (MCP client):

“Show me the last 10 errors from the last hour.”

→ The agent invokes list_logs with level: "error", since: "-1h", limit: 10.

search_logs

Full-text search across log messages.

Arguments:

Name	Type	Required	Notes
project_id	string	yes
q	string	yes	Search query, 1–512 chars.
limit	int	no	1–200. Default 50.
cursor	string	no	Cursor from previous page.

get_log

Fetch a single log row by id, with full stack trace and metadata. Use this when list_logs shows you something interesting and you want the full payload.

Arguments:

Name	Type	Required
log_id	string	yes

list_analyses

List analyses (AI-generated diagnoses of error patterns) for the scoped project.

Arguments:

Name	Type	Required	Notes
project_id	string	yes
severity	enum	no	low, medium, high, critical.
type	enum	no	reactive (triggered by an error) or scheduled (periodic sweep).
include_archived	bool	no	Default false. Archived analyses are triaged from the dashboard and excluded by default.
limit	int	no	1–200. Default 50.
cursor	string	no	Cursor from previous page.

Default behaviour: archived analyses are hidden, so the response answers “what’s currently broken?” rather than “what’s ever happened?”. Pass include_archived: true for audit / historical queries.

get_analysis

Fetch a single analysis by id, including the full diagnosis, suggested fix, and PR link if autofix opened one.

Arguments:

Name	Type	Required
analysis_id	string	yes

The analysis must belong to the scoped project — cross-project lookups return an error.

Pagination

All list tools use cursor-based pagination:

1. Make a call with no cursor.
2. If next_cursor is non-null, pass it as cursor on the next call to get the next page.
3. When next_cursor is null, you’ve reached the end.

Cursors are timestamp values from the last row of the previous page — timestamp for logs (event time) and created_at for analyses. They’re stable: if a new row appears between calls, it’ll show up on a future “first page” call but won’t shift cursor positions you already have.

Errors

The MCP server distinguishes protocol-level errors (bad method, malformed args) from tool-level errors (the tool ran but couldn’t return a result, e.g., “Project not found”).

Protocol errors use the standard JSON-RPC error envelope:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "project_id does not match the read key's scope"
  }
}

Code	Meaning
-32700	Parse error (request body wasn’t valid JSON)
-32601	Unknown method
-32602	Unknown tool name, or arguments failed schema validation

Tool errors come back as a successful result with isError: true and the message in the content block — this matches the MCP spec so well-behaved clients surface them to the user:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Project not found" }],
    "isError": true
  }
}

You’ll see this for get_* tools when the id doesn’t exist or belongs to a different project, and for any tool when the upstream Supabase query fails.