Agent access · MCP

Connect to Telescope

Telescope runs a Model Context Protocol server so AI agents can check the health of the services your code depends on, and ask whether an active incident explains a failure they are debugging.

Public
Read-only
No authentication
Streamable HTTP

Overview#

The server exposes two read-only tools. It needs no token, account, or configuration beyond the URL, so any agent that supports remote MCP servers can use it.

diagnose_suspected_failureStart here. Confirms or denies whether a suspected failure is upstream, and ranks the services most likely involved.get_active_incidentsLists every open incident across monitored services. Use it when a diagnosis is inconclusive or you need a broad view.

When to use it#

Before digging into your own code, to rule out an upstream outage at a provider you depend on.
When a request to an external service starts failing, timing out, or returning unexpected results.
When you want a status page link to share while an incident is ongoing.

Endpoint#

Add this URL as a remote MCP server in your client.

POSThttps://telescope.littleplanetlabs.com/mcp

Transport: Streamable HTTP, stateless (no session ID)
Methods: POST only. GET and DELETE return 405.
Responses: JSON. Each tool returns one text content item containing a JSON document.
Authentication: None

Verify the connection#

List the available tools with a single request. Clients must accept both application/json and text/event-stream.

Terminalshell

curl -X POST https://telescope.littleplanetlabs.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Set up your client#

Pick your agent. Each option registers the server under the name telescope.

Run this once in your terminal:

Terminalshell

claude mcp add --transport http telescope https://telescope.littleplanetlabs.com/mcp

The server is added to the current project for you only (the default local scope). Add --scope user to use it in every project, or --scope project to share it with your team through .mcp.json. Run /mcp inside Claude Code to confirm Telescope is connected.

Add the server with the Codex CLI:

Terminalshell

codex mcp add telescope --url https://telescope.littleplanetlabs.com/mcp

Or add it to your Codex configuration file directly:

~/.codex/config.tomltoml

[mcp_servers.telescope]
url = "https://telescope.littleplanetlabs.com/mcp"

Run codex mcp list to confirm the server is registered.

Add Telescope to .cursor/mcp.json in your project root, or to ~/.cursor/mcp.json to make it available in every workspace:

.cursor/mcp.jsonjson

{
  "mcpServers": {
    "telescope": {
      "url": "https://telescope.littleplanetlabs.com/mcp"
    }
  }
}

If the file already defines other servers, add the telescope entry inside the existing mcpServers object.

Add Telescope to .vscode/mcp.json in your workspace. Its tools become available to GitHub Copilot in agent mode.

.vscode/mcp.jsonjson

{
  "servers": {
    "telescope": {
      "type": "http",
      "url": "https://telescope.littleplanetlabs.com/mcp"
    }
  }
}

If the file already defines other servers, add the telescope entry inside the existing servers object.

Claude on the web and Claude Desktop connect to remote MCP servers as custom connectors.

Open Customize → Connectors.
Click +, then Add custom connector.
Paste the endpoint URL below and click Add.
In a conversation, open the + menu, choose Connectors, and turn Telescope on.

Connector URLurl

https://telescope.littleplanetlabs.com/mcp

On Team and Enterprise plans, an owner adds the connector under Organization settings → Connectors (Add → Custom → Web), and members then connect to it from Customize → Connectors. No OAuth settings are needed.

Add the server with the Gemini CLI:

Terminalshell

gemini mcp add --transport http telescope https://telescope.littleplanetlabs.com/mcp

Or add it to ~/.gemini/settings.json (or .gemini/settings.json in a project). Gemini CLI uses httpUrl for Streamable HTTP servers:

~/.gemini/settings.jsonjson

{
  "mcpServers": {
    "telescope": {
      "httpUrl": "https://telescope.littleplanetlabs.com/mcp"
    }
  }
}

Run /mcp inside Gemini CLI to see connected servers and their tools.

Any MCP client that supports remote servers over Streamable HTTP can connect. Add a server named telescope with this URL; no headers, API keys, or OAuth configuration are required.

Server URLurl

https://telescope.littleplanetlabs.com/mcp

Clients that only speak the legacy HTTP+SSE transport cannot connect, because the endpoint does not serve an event stream over GET.

Tools reference#

Both tools are annotated with readOnlyHint. Results arrive as a single text content item; the examples below show the JSON inside it.

`diagnose_suspected_failure`#

Read-only
10 calls per minute

Diagnoses a suspected service issue. Describe the behavior you are seeing and include any relevant code. Telescope evaluates it against every monitored service and active incident and returns the incident most likely causing the issue, plus a ranked list of the services most likely involved. The ranking is returned even when no incident matches, so a “no outage” answer still points at the most suspect dependencies.

Parameters#

diagnose_suspected_failure parameters
Name	Type	Required	Description
`description`	string	Required	Prose description of the behavior being observed, for example `"Requests failing with 500"`. Must not be empty. Text beyond 8,000 characters is truncated.
`codeSnippets`	string[]	Optional	Relevant code, stack traces, or logs that illustrate the behavior. Blank entries are ignored, only the first 5 are used, and each is truncated to 4,000 characters.

Example argumentsjson

{
  "description": "MMS sends to US customers are accepted by the Twilio API (201, status queued) but recipients never receive them. Started about 30 minutes ago; plain SMS still delivers.",
  "codeSnippets": [
    "const message = await client.messages.create({\n  from: process.env.TWILIO_SHORT_CODE,\n  to: customer.phone,\n  body: \"Your receipt is attached\",\n  mediaUrl: [receiptUrl],\n});",
    "15:32:10 WARN status callback sid=MM5f0c… status=undelivered errorCode=30008"
  ]
}

Response#

diagnose_suspected_failure response fields
Name	Type	Description
`incident`	Incident \| null	The active incident most likely causing the issue, in the same shape as Incident object. Only returned when its probability is at least 0.5; otherwise `null`.
`incidentProbability`	number \| null	Probability (0 to 1) that the incident explains the issue. Null when incident is null.
`incidentConfidence`	number \| null	The model's confidence (0 to 1) in the incident selection. Null when incident is null.
`likelyServices`	Service[]	Up to 5 monitored services ranked by likelihood of involvement, each with `id`, `name`, `statusPageUrl`, and `probability`. Only services at 0.1 or above are listed. Always present, even when no incident matches.
`model`	string \| null	The model that evaluated the request.
`usage`	object \| null	Token usage for the evaluation: `input_tokens` and `output_tokens`.

Example response: matching incidentjson

{
  "incident": {
    "id": "bglgijb1oxj3hq519bfkeonh",
    "provider": {
      "id": "twilio",
      "name": "Twilio",
      "statusPageUrl": "https://status.twilio.com/"
    },
    "name": "MMS Delivery Failures From a Subset of Twilio Short Codes to Multiple Networks in United States",
    "status": "investigating",
    "impact": "minor",
    "shortlink": "https://stspg.io/spg64l3lvkxy",
    "createdAt": "2026-09-17T15:11:40.541Z",
    "updatedAt": "2026-09-17T15:11:40.663Z",
    "latestUpdate": {
      "status": "investigating",
      "body": "Twilio customers may be experiencing MMS delivery failures from a subset of Twilio Short Codes to network subscribers on multiple networks in the United States. Our team is actively investigating this issue.",
      "displayAt": "2026-09-17T15:11:40.659Z"
    }
  },
  "incidentProbability": 0.871,
  "incidentConfidence": 0.904,
  "likelyServices": [
    {
      "id": "twilio",
      "name": "Twilio",
      "statusPageUrl": "https://status.twilio.com/",
      "probability": 0.936
    }
  ],
  "model": "jev-latest",
  "usage": {
    "input_tokens": 2418,
    "output_tokens": 9
  }
}

When no active incident explains the issue, incident is null and likelyServices still ranks the services worth checking:

Example response: no matching incidentjson

{
  "incident": null,
  "incidentProbability": null,
  "incidentConfidence": null,
  "likelyServices": [
    {
      "id": "supabase",
      "name": "Supabase",
      "statusPageUrl": "https://status.supabase.com/",
      "probability": 0.412
    },
    {
      "id": "cloudflare",
      "name": "Cloudflare",
      "statusPageUrl": "https://new.cloudflarestatus.com",
      "probability": 0.137
    }
  ],
  "model": "jev-latest",
  "usage": {
    "input_tokens": 1964,
    "output_tokens": 9
  }
}

Errors and rate limits#

Rate limits

Calls are limited per client IP address to 10 per minute, with a shared ceiling of 200 per minute across all callers. Limits use fixed 60-second windows aligned to the clock minute.

Need more? Teams that want higher limits can email telescope@littleplanetlabs.com to ask about custom limits.

Errors are returned as a tool result with isError: true and a JSON body.

diagnose_suspected_failure error codes
error	When	Fields
`rate_limited`	The caller or global limit for the current window was exceeded.	`scope` (`"user"` or `"global"`), `retryAfterSeconds`
`triage_failed`	The evaluation could not be completed.	`message`

Example error: rate_limitedjson

{
  "error": "rate_limited",
  "scope": "user",
  "retryAfterSeconds": 42
}

Example error: triage_failedjson

{
  "error": "triage_failed",
  "message": "<reason the evaluation could not run>"
}

An empty or missing description is rejected before the diagnosis runs. That result also has isError: true, but carries a plain-text validation message instead of a JSON body.

`get_active_incidents`#

Read-only
No input
Not rate limited

Returns every currently active incident, including its provider, impact, status, timestamps, and latest update. Resolved incidents and scheduled maintenance are not included.

Parameters#

None. Call the tool with an empty arguments object, {}.

Response#

get_active_incidents response fields
Name	Type	Description
`activeIncidents`	Incident[]	Every open incident, most recently updated first. See Incident object. An empty array means all monitored services are operational.
`checkedAt`	string	ISO 8601 timestamp of when the check ran.

Example responsejson

{
  "activeIncidents": [
    {
      "id": "bglgijb1oxj3hq519bfkeonh",
      "provider": {
        "id": "twilio",
        "name": "Twilio",
        "statusPageUrl": "https://status.twilio.com/"
      },
      "name": "MMS Delivery Failures From a Subset of Twilio Short Codes to Multiple Networks in United States",
      "status": "investigating",
      "impact": "minor",
      "shortlink": "https://stspg.io/spg64l3lvkxy",
      "createdAt": "2026-09-17T15:11:40.541Z",
      "updatedAt": "2026-09-17T15:11:40.663Z",
      "latestUpdate": {
        "status": "investigating",
        "body": "Twilio customers may be experiencing MMS delivery failures from a subset of Twilio Short Codes to network subscribers on multiple networks in the United States. Our team is actively investigating this issue.",
        "displayAt": "2026-09-17T15:11:40.659Z"
      }
    }
  ],
  "checkedAt": "2026-09-17T15:47:44.984Z"
}

When every monitored service is operational:

Example response: all operationaljson

{
  "activeIncidents": [],
  "checkedAt": "2026-09-17T15:47:44.984Z"
}

Incident object#

Incident object fields
Name	Type	Description
`id`	string	Telescope incident ID.
`provider`	object	The affected service: `id`, `name`, and `statusPageUrl`.
`name`	string	Incident title from the provider.
`status`	string	`investigating`, `identified`, or `monitoring`.
`impact`	string \| null	Severity as reported by the provider (for example minor or major), or null when the provider does not rate it.
`shortlink`	string \| null	Link to the incident on the provider's status page.
`createdAt`	string	ISO 8601 timestamp when the incident was opened.
`updatedAt`	string	ISO 8601 timestamp of the most recent change.
`latestUpdate`	object \| null	Most recent provider update: `status`, `body`, and `displayAt`.

Usage tips#

Call diagnose_suspected_failure first when a failure appears. Include exact error messages and status codes in description, and put the failing call, stack trace, or log lines in codeSnippets. Its targeted answer uses far fewer tokens than the full incident list.
Call get_active_incidents only when the diagnosis is inconclusive or you need every open incident. It is not rate limited, but it returns everything.
Treat a null incident as “no known outage,” not “nothing is wrong.” Check the top entries in likelyServices before assuming the bug is local.
Share the incident's shortlink or the provider's statusPageUrl when reporting an outage.
On rate_limited, wait retryAfterSeconds before calling again.

Agent instructions#

Paste this into AGENTS.md, CLAUDE.md, or your agent's rules file so it uses Telescope without being asked:

AGENTS.mdmarkdown

## Service status (Telescope MCP)

- When you suspect a failure may be upstream at a third-party service (errors, timeouts, 5xx, or unexpected responses), call the `telescope` MCP server's `diagnose_suspected_failure` tool first, before assuming the bug is in local code. Give a short description of the behavior and pass the failing code, stack trace, or logs as `codeSnippets`.
- Call `get_active_incidents` only when the diagnosis is inconclusive or you need a broad view of open incidents. It returns everything and costs more tokens.
- If either tool surfaces a relevant incident, tell me before changing code and include the incident's status page link.
- If a tool returns `rate_limited`, wait `retryAfterSeconds` before trying again. Do not retry in a loop.

Limits and scope#

The server is read-only. It cannot manage providers, webhooks, notifications, or settings.
Results cover only the services this Telescope instance monitors. diagnose_suspected_failure chooses among those services and their active incidents.
diagnose_suspected_failure results are model-generated probabilities. Treat them as a lead to verify, not a confirmed diagnosis.

Keep secrets out of diagnoses

The description and snippets you send are evaluated by an external AI model. Remove API keys, tokens, and personal data before calling diagnose_suspected_failure.

Want the human view? See the status overview →

Overview#

When to use it#

Endpoint#

Verify the connection#

Set up your client#

Tools reference#

diagnose_suspected_failure#

Parameters#

Response#

Errors and rate limits#

get_active_incidents#

Parameters#

Response#

Incident object#

Usage tips#

Agent instructions#

Limits and scope#

`diagnose_suspected_failure`#

`get_active_incidents`#