README

An extension for Laravel Telescope that exposes telemetry data via the Model Context Protocol (MCP) to AI assistants (e.g., Cursor, Claude, Copilot Chat). Ideal for developers who use Telescope to inspect application metrics and require quick, precise insights.

Overview

Telescope MCP exposes all Laravel Telescope telemetry data via the Model Context Protocol (MCP), enabling AI assistants to directly access and analyze application metrics. This provides developers with instant insights into logs, slow queries, HTTP requests, exceptions, jobs, and more through natural language queries.

Requirements

• PHP 8.3+
• Laravel 11, 12 or 13
• Laravel Telescope 5.0+

Important

The HTTP MCP endpoint is not authenticated by default. If you expose it online, enable authentication first (see "Secure Streamable HTTP in IDEs").

Status: ✅ 19 MCP tools fully operational and integrated

What's New in v1.0

🎉 Now powered by the official Laravel/MCP package!

• Built on Laravel's official MCP framework for better maintainability and long-term support
• Improved architecture with cleaner tool definitions using Laravel\Mcp\Server\Tool
• Enhanced schema validation with JsonSchema builder
• Better request handling with Laravel\Mcp\Request and Laravel\Mcp\Response
• Full backward compatibility maintained - all 19 tools work identically
• Ready for future Laravel/MCP features (Resources, Prompts, OAuth authentication)

Quick Start

1. Install the package:

   composer require lucianotonet/laravel-telescope-mcp --dev

2. Auto-configure your MCP client:

   php artisan telescope-mcp:install

   💡 Automatically detects and configures: Cursor, Claude Code, Windsurf, Cline, Gemini App, Antigravity, Codex, and OpenCode.

3. Restart your IDE/editor and start using tools!

Detailed Installation

1. Require Package

composer require lucianotonet/laravel-telescope-mcp --dev

2. Configure MCP Client

You can use the automatic installer or configure manually.

Option A: Automatic Installation (Recommended)

php artisan telescope-mcp:install

This command will:

• Detect installed MCP clients
• Generate the correct configuration file (mcp.json, settings.json, etc.)
• Set up the server in stdio mode

Option B: Manual Configuration Add the following to your MCP client's configuration file:

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["artisan", "telescope-mcp:server"],
      "cwd": "/path/to/your/project",
      "env": {
        "APP_ENV": "local"
      }
    }
  }
}

Important

Antigravity users: Antigravity does not support the cwd property. You must use the absolute path to artisan in the args array and it is recommended to add "MCP_MODE": "stdio" to the env object.

3. Verify Installation

Run the server manually to ensure it's working:

php artisan telescope-mcp:server

It should run silently (logging to stderr) and wait for JSON-RPC input.

Manual Configuration per Assistant

If you prefer to configure manually, add the following to your assistant's configuration file:

Cursor, Windsurf, Cline

File: mcp.json or cline_mcp_settings.json

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["artisan", "telescope-mcp:server"],
      "cwd": "/absolute/path/to/your/project",
      "env": {
        "APP_ENV": "local"
      }
    }
  }
}

Claude Code (CLI)

You can configure via the ~/.claude/mcp.json file (same format as Cursor) or via command:

claude mcp add -s local -t stdio laravel-telescope php artisan telescope-mcp:server

Antigravity

File: mcp_config.json (Global configuration only)

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["/absolute/path/to/your/project/artisan", "telescope-mcp:server"],
      "env": {
        "APP_ENV": "local",
        "MCP_MODE": "stdio"
      }
    }
  }
}

OpenCode

OpenCode uses a different key and requires the absolute path to artisan.

File: opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "laravel-telescope": {
      "type": "local",
      "enabled": true,
      "command": ["php", "/absolute/path/to/your/project/artisan", "telescope-mcp:server"],
      "environment": {
        "APP_ENV": "local"
      }
    }
  }
}

Codex (TOML)

File: config.toml

[mcpServers.laravel-telescope]
command = "php"
args = ["artisan", "telescope-mcp:server"]
cwd = "/absolute/path/to/your/project"

[mcpServers.laravel-telescope.env]
APP_ENV = "local"

Troubleshooting (Stdio)

PHP or Artisan not found

Ensure php is in your global PATH or use the absolute path to the PHP executable. On Windows, use double backslashes \\ in JSON/TOML paths.

Permissions

Ensure the AI assistant has permission to read/write in your Laravel project's storage directory, where Telescope stores the data.

MCP Logs

If tools don't appear, check your assistant's error logs (e.g., Cursor Output > MCP). The command php artisan telescope-mcp:server should run without errors if executed manually in the terminal.

Using MCP Inspector (Browser UI / HTTP)

If you want to test your server from the browser using @modelcontextprotocol/inspector, use HTTP transport with your MCP endpoint URL.

1. Start Inspector against a remote/public endpoint

npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp"

2. Start Inspector against a local HTTPS endpoint

If your local certificate is self-signed (common with *.test domains), disable TLS verification for Node in your current shell:

# PowerShell
$env:NODE_TLS_REJECT_UNAUTHORIZED='0'
npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-local-domain.test/telescope-mcp"

3. If default inspector ports are busy

Inspector uses ports 6274 (UI) and 6277 (proxy) by default. If you get "PORT IS IN USE":

# PowerShell
$env:CLIENT_PORT='6284'
$env:SERVER_PORT='6287'
npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp"

4. Optional auth headers

If your MCP route is protected by middleware, pass headers:

npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp" --header "Authorization: Bearer YOUR_TOKEN"

5. Quick health check

• GET /telescope-mcp returning 405 is expected.
• Use POST /telescope-mcp for MCP JSON-RPC requests.

Secure Streamable HTTP in IDEs

This package now supports built-in bearer token authentication for the HTTP MCP endpoint.

1. Enable auth in Laravel (.env)

MCP_BEARER_TOKEN=replace-with-a-long-random-token

You can also use TELESCOPE_MCP_BEARER_TOKEN instead of MCP_BEARER_TOKEN. Auth is automatically enabled when one of these token env vars is present. If you prefer explicit control, set:

TELESCOPE_MCP_AUTH_ENABLED=true

Generate a token example:

php -r "echo bin2hex(random_bytes(32)), PHP_EOL;"

2. IDE UI mapping (Streamable HTTP)

For IDEs that ask fields like:

• Name
• Streamable HTTP
• URL
• Bearer token env var
• Headers / Headers from environment variables

Use:

• Name: laravel-telescope-online (or any name)
• Transport: Streamable HTTP
• URL: https://your-domain.com/telescope-mcp
• Bearer token env var: MCP_BEARER_TOKEN

If your IDE does not support "Bearer token env var", set headers manually:

• Key: Authorization
• Value: Bearer <your-token>

If your IDE supports "headers from env variables", prefer:

• Key: Authorization
• Value: Bearer ${MCP_BEARER_TOKEN}

3. Local and online examples

• Local URL: https://your-local-domain.test/telescope-mcp
• Online URL: https://your-public-domain.com/telescope-mcp

Reference: OpenAI Codex MCP docs (https://developers.openai.com/codex/mcp/).

How to Use

Once connected, you can use the MCP tools directly in your AI assistant:

# List recent HTTP requests
@laravel-telescope-mcp requests --limit 5

# Details of a specific exception
@laravel-telescope-mcp exceptions --id 123456

# Find slow queries
@laravel-telescope-mcp queries --slow true --limit 10

Usage Examples

Direct MCP Tool Usage (Recommended)

Once connected, you can use the MCP tools directly in your AI assistant:

# List recent HTTP requests
@laravel-telescope-mcp requests --limit 5

# Get details of a specific exception
@laravel-telescope-mcp exceptions --id 123456

# Find slow database queries
@laravel-telescope-mcp queries --slow true --limit 10

# Check recent logs
@laravel-telescope-mcp logs --level error --limit 5

Natural Language Queries

• "Show me the last 5 error logs from the application"
• "Identify SQL queries taking longer than 100ms"
• "Display all failed jobs from the last hour"
• "Summarize HTTP requests with 5xx status codes"

The AI will automatically use the appropriate MCP tools to fetch and analyze the data.

Available Tools

All 19 MCP tools are fully operational and provide structured responses with both human-readable text and JSON data.

Current Status & Features

✅ MCP Integration Status

• 19 MCP tools operational: All major Telescope features are now accessible via MCP
• Native Cursor integration: Tools work directly within Cursor without external commands
• Structured responses: Each tool returns both human-readable text and JSON data
• Real-time data access: Direct access to Telescope telemetry without HTTP requests

🚀 Key Benefits

• No more cURL needed: Use MCP tools directly in your AI assistant
• Instant insights: Get application metrics through natural language
• Structured data: Both readable summaries and programmatic access
• Full Telescope coverage: Access to all major monitoring features

📊 Response Format

Each MCP tool provides:

• Human-readable output: Formatted tables and summaries
• JSON data: Structured data for programmatic processing
• MCP compliance: Standard MCP response format

🔧 Tool Capabilities

• List operations: Get overviews with customizable limits
• Detail views: Drill down into specific entries by ID
• Filtering: Apply filters like status, level, time ranges
• Performance metrics: Track slow queries, failed jobs, errors

Configuration

• Authentication: Use built-in bearer auth with TELESCOPE_MCP_AUTH_ENABLED=true and MCP_BEARER_TOKEN (or TELESCOPE_MCP_BEARER_TOKEN), or protect with Laravel middleware (auth:sanctum, auth.basic).
• Endpoint Path: Customize TELESCOPE_MCP_PATH or modify in config/telescope-mcp.php.
• Middleware: Set TELESCOPE_MCP_MIDDLEWARE as comma-separated list (e.g., api,auth:sanctum).
• Logging: Enable or disable internal MCP logging.
• Timeouts & Limits: Adjust request timeouts and payload limits as needed.

Advanced

See config/telescope-mcp.php for:

• Custom middleware stacks
• Operation-specific settings
• Route and namespace overrides

Performance & Monitoring

Real-time Insights

• HTTP Requests: Monitor incoming traffic, response times, and status codes
• Database Queries: Track slow queries and optimize performance
• Application Errors: Get detailed stack traces and error context
• Job Processing: Monitor queue performance and failures
• Cache Operations: Track cache hit/miss ratios and performance

Data Retention

• Configurable limits: Set appropriate limits for each tool based on your needs
• Efficient queries: Tools use optimized Telescope queries for fast responses
• Memory management: Responses are formatted efficiently for MCP clients

Contributing

Contributions are welcome. Please submit issues or pull requests following our CONTRIBUTING.md guidelines.

License

Licensed under MIT. See LICENSE for details.