Telescope MCP Setup

fluttersdk_telescope extends the artisan MCP server with 10 runtime-inspection tools (telescope_*). This page covers everything needed to make those tools appear in Claude Code, Cursor, or any other MCP-compatible client.

Prerequisite: no prior artisan setup is required. Telescope's telescope:install command scaffolds the artisan harness on first run, and fluttersdk_artisan is pulled in transitively through telescope's pubspec.

Step 1: Add the dependency

Add fluttersdk_telescope to your pubspec.yaml under dependencies (not dev_dependencies, because TelescopePlugin is imported by lib/main.dart):

# pubspec.yaml
dependencies:
  fluttersdk_telescope: ^0.0.4

Run dart pub get after editing.

Step 1a: bootstrap with telescope:install (optional but recommended)

If you only want the MCP tools, jump to Step 2. If you also want the 11 CLI commands wired to the artisan dispatcher, run the one-shot bootstrap now; it scaffolds bin/dispatcher.dart, registers the plugin, and patches lib/main.dart in one go:

dart run fluttersdk_telescope telescope:install

After install, the consumer's fast-cli is available at ./bin/fsa (native AOT, ~110ms warm).

Step 2: Install the Flutter-side plugin

Inside lib/main.dart, install TelescopePlugin before runApp, gated at the call site so the entire subsystem tree-shakes out of release builds. telescope:install writes kDebugMode; the snippet below uses !kReleaseMode, which also keeps telescope in profile builds (see Call-site guard). When using the Magic framework, place the call before Magic.init() so the Http facade is wired in time:

import 'package:flutter/foundation.dart';
import 'package:fluttersdk_telescope/telescope.dart';
import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only)

Future main() async {
  if (!kReleaseMode) {
    TelescopePlugin.install();
  }
  await Magic.init(...);
  if (!kReleaseMode) {
    // Optional: when using the Magic framework, register its adapters and watchers.
    // Call MagicTelescopeIntegration.install() after Magic.init(). Ships in the
    // magic_devtools dev_dependency (import 'package:magic_devtools/telescope.dart').
    MagicTelescopeIntegration.install();
  }
  runApp(MagicApplication());
}

TelescopePlugin.install() registers all ext.telescope.* VM Service extensions and starts the ring buffers. Extensions are registered via registerExtensionIdempotent (from artisan), so hot restarts are safe.

Step 3: Register TelescopeArtisanProvider in bin/dispatcher.dart

If you ran Step 1a (telescope:install), the provider is registered automatically via lib/app/_plugins.g.dart (the codegen barrel auto-discovered by bin/dispatcher.dart); skip to Step 4.

For manual wiring, open bin/dispatcher.dart and add FluttersdkTelescopeArtisanProvider() to the baseProviders list:

import 'package:fluttersdk_artisan/artisan.dart';
import 'package:fluttersdk_telescope/cli.dart';  // FluttersdkTelescopeArtisanProvider typedef

Future main(List args) async {
  exit(await runArtisan(
    args,
    baseProviders: [
      FluttersdkTelescopeArtisanProvider(),
      // ...other providers (DuskArtisanProvider, etc.)
    ],
  ));
}

The cli.dart barrel exports FluttersdkTelescopeArtisanProvider (a typedef alias for TelescopeArtisanProvider) so consumer-side auto-discovery can use a stable name.

Step 4: Ensure the artisan MCP server entry is present

The telescope tools surface through artisan's MCP server. The .mcp.json entry must point at dart run fluttersdk_artisan:mcp (not a separate telescope entry). If you ran dart run fluttersdk_artisan mcp:install during artisan setup, the entry is already in place:

{
  "mcpServers": {
    "fluttersdk": {
      "command": "dart",
      "args": ["run", "fluttersdk_artisan:mcp"],
      "cwd": "."
    }
  }
}

The cwd field must resolve to the directory containing pubspec.yaml and bin/dispatcher.dart. The server reads both at startup: pubspec.yaml for the project root detection and bin/dispatcher.dart (via the registered providers) for the plugin tool catalog.

Step 5: Reconnect the MCP server

After editing bin/dispatcher.dart or .mcp.json, the running MCP server process must be restarted for the new tools to appear in the catalog:

Claude Code:

/mcp reconnect fluttersdk

Cursor / Windsurf: Reload the MCP panel or restart the IDE session.

Claude Desktop: Fully quit and relaunch.

Step 6: Start the Flutter app and verify

Start the app via artisan so the state file is written:

./bin/fsa start              # web (chrome, default)
./bin/fsa start --device=macos  # desktop

Then ask the agent to check telescope connectivity:

telescope_tail limit=5

A successful response returns a JSON array of recent log records. An empty array means the app is running but no logs have been emitted yet. An error response means the VM Service URI in ~/.artisan/state.json is stale; run ./bin/fsa stop && ./bin/fsa start to refresh it.

Filtering telescope tools

To hide specific telescope tools from the agent's catalog, add deny rules to .artisan/mcp.json:

{
  "packages": {
    "allow": null,
    "deny": []
  },
  "tools": {
    "allow": null,
    "deny": ["telescope_dumps", "telescope_gates"]
  }
}

To expose only telescope tools (hiding substrate and dusk tools):

{
  "packages": {
    "allow": ["fluttersdk_telescope"],
    "deny": []
  },
  "tools": {
    "allow": null,
    "deny": []
  }
}

After editing .artisan/mcp.json, run /mcp reconnect fluttersdk in Claude Code to reload the filter. See the artisan filter reference for the full three-layer precedence rules (file, env vars, CLI flags).

Related

• artisan MCP setup: full client matrix (Cursor, Claude Desktop, VS Code, Windsurf, JetBrains, Cline, OpenCode, Gemini CLI).
• Overview: how the 10 tools surface through TelescopeArtisanProvider and route through the VM Service.
• Tool reference: per-tool input schema, output shape, and example invocations.