Telescope MCP Tool Reference

Catalog of every MCP tool contributed by fluttersdk_telescope via TelescopeArtisanProvider.mcpTools(). All 9 tools use the telescope_ prefix and dispatch through ext.telescope.* VM Service extensions registered inside the running Flutter app by registerAllTelescopeExtensions().

Requires a running app. Every telescope tool dispatches via the VM Service. Boot the app via the artisan fast-cli (./bin/fsa start) or the MCP equivalent (artisan_start) and confirm artisan_status shows a live vmServiceUri before invoking these tools.

Common conventions
telescope_tail
telescope_requests
telescope_exceptions
telescope_events
telescope_gates
telescope_dumps
telescope_queries
telescope_caches
telescope_clear
Related

Common Conventions

All buffer-reading tools (every tool except telescope_clear) share these conventions:

Newest-first ordering. The most recent record is always at index 0 of the returned array.
limit parameter. All buffer tools accept an optional limit: integer parameter that caps the number of records returned. When omitted, the entire ring buffer is returned (subject to the ring-buffer capacity, typically 200-500 records depending on buffer type).
Empty array on empty buffer. When the buffer holds no records (fresh start or after telescope_clear), the response is {"records": []}. This is not an error.
JSON envelope. Every tool returns a JSON object. The outer shape is always {"records": [...]}. Individual record field shapes are documented per tool below.
Error shape. On failure (app not running, VM Service unreachable), McpServer returns CallToolResult with isError: true and an actionable plain-text message.

telescope_tail

Return recent log records from the running Flutter app.

Reads the Telescope log ring buffer populated by every package:logging Logger call in the app. Use this to inspect what the app logged without scraping flutter run stdout via artisan_logs.

VM Service extension: ext.telescope.console

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of records to return, newest first. Omit for the whole buffer (cap enforced by ring-buffer size, typically 200).
`level`	string	no	Minimum log level to include. Common values: `FINE`, `INFO`, `WARNING`, `SEVERE`, `SHOUT`. Omit for all levels.

Output Shape

{
  "records": [
    {
      "level": "WARNING",
      "levelValue": 900,
      "message": "Monitor check timed out after 30s",
      "loggerName": "MonitorController",
      "time": "2026-05-20T14:32:10.123Z",
      "error": "TimeoutException: ...",
      "stackTrace": "#0 MonitorController.check ..."
    }
  ]
}

Field	Type	Always present	Description
`level`	string	yes	Log level name (e.g. `INFO`, `WARNING`, `SEVERE`)
`levelValue`	integer	yes	Numeric level value from `package:logging`
`message`	string	yes	Log message string
`loggerName`	string	yes	Name of the `Logger` instance that emitted the record
`time`	string	yes	ISO 8601 UTC timestamp
`error`	string	no	Error object stringified, when one was attached
`stackTrace`	string	no	Stack trace stringified, when one was attached

Example Invocations

# Last 10 log lines at any level
telescope_tail limit=10

# Last 20 WARNING-and-above entries
telescope_tail limit=20 level=WARNING

# All SEVERE entries in the buffer
telescope_tail level=SEVERE

telescope_exceptions: uncaught exceptions (not expected try/catch flows)
telescope_requests: HTTP traffic
telescope_clear: wipe the buffer before a repro

telescope_requests

Return recent HTTP request records from the running Flutter app.

Reads the Telescope HTTP ring buffer populated by the Telescope Dio interceptor or any TelescopeHttpAdapter the app installs (e.g. MagicHttpFacadeAdapter from the magic package). Use this to debug API issues without instrumenting the app or watching network panels in DevTools.

VM Service extension: ext.telescope.requests

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of HTTP records to return, newest first. Omit for the whole buffer.

Output Shape

{
  "records": [
    {
      "url": "https://api.example.com/monitors",
      "method": "GET",
      "statusCode": 200,
      "durationMs": 142,
      "isError": false,
      "timestamp": "2026-05-20T14:32:11.456Z",
      "requestHeaders": {
        "Authorization": "Bearer eyJ..."
      },
      "requestBody": null,
      "responseBody": "{\"data\": [...]}"
    }
  ]
}

Field	Type	Always present	Description
`url`	string	yes	Full request URL
`method`	string	yes	HTTP method (`GET`, `POST`, etc.)
`statusCode`	integer	yes	HTTP status code; 0 when the call failed before a response
`durationMs`	integer	yes	Round-trip time in milliseconds
`isError`	boolean	yes	True when the adapter classified the call as failed
`timestamp`	string	yes	ISO 8601 UTC timestamp of when the request was recorded
`requestHeaders`	object	no	Request headers as a `Map`
`requestBody`	string	no	Request body as a string, when present and readable
`responseBody`	string	no	Response body snippet, when present
`attributedHeuristically`	boolean	no	True when the adapter used best-effort FIFO attribution for concurrent requests

Example Invocations

# Last 5 HTTP requests
telescope_requests limit=5

# All requests in the buffer
telescope_requests

Notes

Only HTTP calls that go through an installed Telescope adapter are recorded. Raw dart:io HttpClient calls are invisible to this tool.
Pair with telescope_clear before a user action to isolate exactly the traffic that action produces.

telescope_exceptions

Return recent uncaught exception records from the running Flutter app.

Reads the Telescope exception ring buffer populated by the FlutterError.onError hook that TelescopePlugin.install() chains. Use this when a crash or unhandled Exception was thrown and you need the stack without scraping flutter run stdout.

VM Service extension: ext.telescope.exceptions

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of exception records to return, newest first. Omit for the whole buffer.

Output Shape

{
  "records": [
    {
      "exceptionType": "StateError",
      "message": "Bad state: Stream has already been listened to",
      "time": "2026-05-20T14:33:00.789Z",
      "stackTrace": "#0 _StreamController._subscribe ...",
      "isolate": "main"
    }
  ]
}

Field	Type	Always present	Description
`exceptionType`	string	yes	Runtime type name of the exception object
`message`	string	yes	Exception message string
`time`	string	yes	ISO 8601 UTC timestamp
`stackTrace`	string	no	Full stack trace, when available
`isolate`	string	no	Isolate name where the exception was caught

Example Invocations

# Last 3 uncaught exceptions
telescope_exceptions limit=3

# All exceptions in the buffer
telescope_exceptions

Notes

Only uncaught exceptions routed through FlutterError.onError are captured. Expected try/catch flows do not surface here.
The watcher chain-preserves the previous FlutterError.onError handler (e.g. Sentry) so both coexist safely.
Pair with telescope_tail to see what the app logged in the moments before the crash.

telescope_events

Return recent in-app event records from the running Flutter app.

Reads the Telescope events ring buffer populated by MagicEventWatcher whenever Event.dispatch() is called via the Magic Event facade. Use this to trace event-driven side effects (cache invalidation, broadcast echoes, model lifecycle transitions) without adding print statements.

VM Service extension: ext.telescope.events

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of event records to return, newest first. Omit for the whole buffer (cap enforced by ring-buffer size, typically 500).

Output Shape

{
  "records": [
    {
      "eventType": "MonitorChecked",
      "payload": {
        "monitorId": "abc-123",
        "status": "up"
      },
      "time": "2026-05-20T14:34:00.001Z",
      "listenerCount": 3
    }
  ]
}

Field	Type	Always present	Description
`eventType`	string	yes	Runtime class name of the dispatched event
`payload`	object	yes	JSON snapshot of the event payload
`time`	string	yes	ISO 8601 UTC timestamp
`listenerCount`	integer	no	Number of listeners notified at dispatch time, when available

Example Invocations

# Last 10 events
telescope_events limit=10

# All events in the buffer
telescope_events

Notes

Only events dispatched through the Magic Event facade are captured. Raw ChangeNotifier.notifyListeners calls are invisible to this tool.
For Gate authorization checks use telescope_gates; for HTTP traffic use telescope_requests.

telescope_gates

Return recent Gate authorization check records from the running Flutter app.

Reads the Telescope gates ring buffer populated by MagicGateWatcher on every Gate.allows / Gate.denies call via the Magic Gate facade. Use this to debug authorization issues (why a button is hidden, why a route is blocked) without modifying policy classes.

VM Service extension: ext.telescope.gates

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of gate check records to return, newest first. Omit for the whole buffer (cap enforced by ring-buffer size, typically 500).

Output Shape

{
  "records": [
    {
      "ability": "monitors.destroy",
      "result": false,
      "arguments": ["Monitor"],
      "time": "2026-05-20T14:35:00.010Z",
      "userId": "user-42"
    }
  ]
}

Field	Type	Always present	Description
`ability`	string	yes	Ability name passed to `Gate.allows` / `Gate.denies`
`result`	boolean	yes	`true` when the gate allowed the action; `false` when denied
`arguments`	array	yes	List of argument values (class name strings or serialized primitives)
`time`	string	yes	ISO 8601 UTC timestamp
`userId`	string	no	Authenticated user ID at check time, when available

Example Invocations

# Last 20 gate checks
telescope_gates limit=20

# All gate checks in the buffer
telescope_gates

Notes

Only checks routed through the Magic Gate facade are captured. Direct policy class calls are not recorded.
Pair with telescope_clear before walking a guarded flow to isolate just the relevant checks.

telescope_dumps

Return recent debugPrint output records from the running Flutter app.

Reads the Telescope dumps ring buffer populated by DumpWatcher, which overrides debugPrint globally. Use this to read print() / debugPrint() output from within the running app without scraping flutter run stdout.

VM Service extension: ext.telescope.dumps

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of dump records to return, newest first. Omit for the whole buffer (cap enforced by ring-buffer size, typically 500).

Output Shape

{
  "records": [
    {
      "message": "[MonitorController] reloading monitors...",
      "time": "2026-05-20T14:36:00.200Z",
      "wrapWidth": 80
    }
  ]
}

Field	Type	Always present	Description
`message`	string	yes	Full message string passed to `debugPrint`
`time`	string	yes	ISO 8601 UTC timestamp
`wrapWidth`	integer	no	Wrap width passed to the original `debugPrint` call, when provided

Example Invocations

# Last 10 debugPrint calls
telescope_dumps limit=10

# All dump records in the buffer
telescope_dumps

Notes

Only output routed through the debugPrint global override is captured. dart:io stdout.write calls are invisible to this tool.
DumpWatcher gates on kDebugMode: release builds tree-shake it entirely.
For structured logs use telescope_tail; for crashes use telescope_exceptions.

telescope_queries

Return recent database query records from the running Flutter app.

Reads the Telescope queries ring buffer populated by MagicQueryWatcher, which subscribes to magic's QueryExecuted event dispatched by the Magic QueryBuilder. Each record carries the SQL string, bindings, execution time, and connection name. Use this to inspect what queries the app dispatched without attaching a separate SQL profiler.

VM Service extension: ext.telescope.queries

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of query records to return, newest first. Omit for the whole buffer (cap enforced by ring-buffer size, typically 500).

Output Shape

{
  "records": [
    {
      "sql": "SELECT * FROM monitors WHERE team_id = ? LIMIT 50",
      "bindings": ["team-abc"],
      "timeMs": 4,
      "connectionName": "default",
      "time": "2026-05-20T14:37:00.100Z"
    }
  ]
}

Field	Type	Always present	Description
`sql`	string	yes	SQL string the QueryBuilder dispatched to the underlying driver
`bindings`	array	yes	Positional or named query bindings
`timeMs`	integer	yes	Execution time in milliseconds reported by magic's QueryBuilder
`connectionName`	string	yes	Connection name; `"default"` when the consumer did not name it
`time`	string	yes	ISO 8601 UTC timestamp

Example Invocations

# Last 5 queries
telescope_queries limit=5

# All queries in the buffer
telescope_queries

Notes

Only queries that go through magic's QueryBuilder (dispatching QueryExecuted via EventDispatcher) are recorded. Raw sqlite3 or direct Dio SQL calls bypass this tool.
For Magic Cache traffic use telescope_caches; for HTTP use telescope_requests; for log lines use telescope_tail.

telescope_caches

Return recent Magic Cache operation records from the running Flutter app.

Reads the Telescope caches ring buffer populated by MagicCacheWatcher, which subscribes to magic's CacheHit / CacheMiss / CachePut / CacheForget / CacheFlush events. Each record carries timestamp, operation tag, cache key, and optional TTL. Use this to inspect cache traffic without instrumenting the consumer code.

VM Service extension: ext.telescope.caches

Input Schema

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of cache records to return, newest first. Omit for the whole buffer (cap enforced by ring-buffer size, typically 500).

Output Shape

{
  "records": [
    {
      "operation": "miss",
      "key": "monitors.team-abc",
      "time": "2026-05-20T14:38:00.300Z",
      "ttlMs": 300000
    }
  ]
}

Field	Type	Always present	Description
`operation`	string	yes	One of: `hit`, `miss`, `put`, `forget`, `flush`
`key`	string	yes	Cache key string
`time`	string	yes	ISO 8601 UTC timestamp
`ttlMs`	integer	no	TTL in milliseconds, when the operation included a TTL

Example Invocations

# Last 20 cache operations
telescope_caches limit=20

# All cache operations in the buffer
telescope_caches

Notes

Only Magic Cache facade calls dispatch the watcher events. Raw driver-level cache calls bypass this tool.
For DB queries use telescope_queries; for HTTP use telescope_requests.

telescope_clear

Clear every Telescope ring buffer.

Wipes all ring buffers in one call so the next telescope_tail / telescope_requests / telescope_exceptions / telescope_events / telescope_gates / telescope_dumps / telescope_queries / telescope_caches returns only records produced after this clear. Useful as a "set zero" before reproducing a bug or capturing the output of a specific user action.

VM Service extension: ext.telescope.clear

Input Schema

No parameters.

Output Shape

{
  "cleared": true
}

Field	Type	Always present	Description
`cleared`	boolean	yes	Always `true` on success

Example Invocations

# Clear all buffers before a repro
telescope_clear

# Common pattern: clear, perform the action, then read
telescope_clear
# ... trigger the user action ...
telescope_requests limit=20
telescope_tail limit=50

Notes

Idempotent: safe to call when buffers are already empty.
Does NOT affect the live package:logging stream; only the captured ring buffers.
The ext.telescope.pause and ext.telescope.resume extensions exist in the running app but are not exposed as MCP tools in the current release (V1.x backlog).

Overview: how the 9 tools surface through TelescopeArtisanProvider and route through the VM Service.
Setup guide: install telescope, register TelescopeArtisanProvider, and connect Claude Code.
artisan MCP tool reference: the 10 substrate tools (artisan_start, artisan_stop, artisan_tinker, etc.) and filter configuration.

Telescope MCP Tool Reference

Table of Contents

Common Conventions

telescope_tail

Input Schema

Output Shape

Example Invocations

Related Tools

telescope_requests

Input Schema

Output Shape

Example Invocations

Notes

telescope_exceptions

Input Schema

Output Shape

Example Invocations

Notes

telescope_events

Input Schema

Output Shape

Example Invocations

Notes

telescope_gates

Input Schema

Output Shape

Example Invocations

Notes

telescope_dumps

Input Schema

Output Shape

Example Invocations

Notes

telescope_queries

Input Schema

Output Shape

Example Invocations

Notes

telescope_caches

Input Schema

Output Shape

Example Invocations

Notes

telescope_clear

Input Schema

Output Shape

Example Invocations

Notes

Related