MCP server (Bilge)

Connect Cursor, Claude Desktop, or any MCP client to your Bilge account over HTTP JSON-RPC. Use the same Personal access token you create under Profile for the REST API.

Endpoint: POST https://bilge.sh/mcp/bilge
Auth: Authorization: Bearer <sanctum_token> (or ?api_token= on GET-style clients only — prefer the header)
Throttle: 120 requests/minute per user (same as /api/v1).

Cursor configuration

Add to your project or user MCP config (replace host and token):

{
  "mcpServers": {
    "bilge": {
      "url": "https://bilge.sh/mcp/bilge",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

Local dev example: http://bilge.test/mcp/bilge

Tools (17)

Tool	Purpose
`bilge_me`	Current user, organizations, teams
`bilge_list_projects`	Projects you can access
`bilge_create_project`	Create a project (returns full `api_key` once)
`bilge_get_project`	Single project metadata
`bilge_list_grouped_errors`	Grouped issues with search/status filters
`bilge_error_group_count`	Count of matching groups
`bilge_occurrence_count`	Raw occurrence count
`bilge_list_occurrences`	Occurrences in a fingerprint group
`bilge_get_occurrence`	Full stack, context, breadcrumbs
`bilge_list_issue_comments`	Issue thread comments
`bilge_comment_on_error`	Post a comment (optional `parent_id` reply)
`bilge_resolve_error`	Resolve group (optional comment)
`bilge_open_error`	Re-open group
`bilge_ignore_error`	Ignore group
`bilge_snooze_error`	Snooze with preset or ISO8601 `until`
`bilge_unsnooze_error`	Clear snooze
`bilge_query_telemetry`	Query traces, logs, jobs, mail, gates, metrics, …

REST parity: every Sanctum v1 route in the REST API has a matching tool except ingest (project API key) and operator routes.

Resources

URI	Content
`bilge://openapi/v1.yaml`	OpenAPI 3 spec
`bilge://docs/api`	REST API markdown reference
`bilge://docs/ingest`	Ingest API markdown reference
`bilge://docs/mcp`	This page (connection + catalog)

Prompts

Prompt	Use when
`triage_error`	You have an `error_id` and need resolve/snooze/ignore workflow
`debug_slow_request`	Slow endpoints, failing jobs, log correlation
`investigate_regression`	Multi-release or post-deploy spike

Example JSON-RPC

List tools (after MCP initialize / notifications/initialized):

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Call a tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "bilge_list_projects",
    "arguments": {}
  }
}

Security

Treat personal access tokens like passwords. Scope tokens to people who can triage production.
MCP exposes the same project visibility as the web UI; 404 when a resource is not accessible.
Ingest and project API keys are not used on this endpoint — send events via the Ingest API instead.