Documentation / MCP Server

MCP Server

Connect AI assistants to your GhostlyX analytics data using the Model Context Protocol. Works with OpenCode, Claude Desktop, Cursor, and any MCP-compatible tool.

Overview

The GhostlyX MCP server lets AI assistants query your analytics data through a structured, authenticated interface. Instead of copying and pasting numbers from the dashboard, you can ask your AI assistant questions like "What are my top 10 pages this week?" or "Is my site up right now?" and it will pull the data directly from GhostlyX.

1

Generate an API token

Create a Sanctum API token from your account settings. The same tokens work for both the REST API and the MCP server.

2

Configure your AI assistant

Add GhostlyX as a remote MCP server in your AI tool's configuration file with the /mcp/v1 endpoint.

3

Start asking questions

Your AI assistant can now query site stats, traffic sources, uptime, goals, funnels, and more.

1

Generate an API token

Go to Settings → API Tokens in your GhostlyX dashboard and create a new token. Give it a descriptive name like "OpenCode MCP" so you can identify it later. Copy the token immediately because it will not be shown again.

Manage API tokens
2

Configure your AI assistant

Add GhostlyX as a remote MCP server in your AI tool's configuration. The endpoint is https://ghostlyx.com/mcp/v1 and authentication uses a Bearer token header. Below are configuration examples for popular tools.

OpenCode opencode.json

Add this to your opencode.json file in your project root. Set the GHOSTLYX_API_TOKEN environment variable to your API token. 

{
  "mcp": {
    "ghostlyx": {
      "type": "remote",
      "url": "https://ghostlyx.com/mcp/v1",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:GHOSTLYX_API_TOKEN}"
      }
    }
  }
}
Claude claude_desktop_config.json

Add this to your Claude Desktop configuration file. On macOS this is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is at %APPDATA%\Claude\claude_desktop_config.json. 

{
  "mcpServers": {
    "ghostlyx": {
      "url": "https://ghostlyx.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
Cursor .cursor/mcp.json

Create or edit the .cursor/mcp.json file in your project root. 

{
  "mcpServers": {
    "ghostlyx": {
      "url": "https://ghostlyx.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
Any Generic MCP client

Any MCP-compatible tool can connect using the endpoint and a Bearer token header. The exact configuration format varies by tool, but you always need these two values:

Endpoint https://ghostlyx.com/mcp/v1
Auth header Authorization: Bearer YOUR_API_TOKEN
3

Available tools

The MCP server exposes 10 tools. Most are read-only. Tools that can create or modify data are marked as read/write and enforce the same role-based permissions as the GhostlyX dashboard.

list_sites Read

List all sites you own and sites you are a member of.

Parameters: None

get_site_stats Read

Aggregate pageviews, visitors, bounce rate, and average visit duration.

Parameters: site_identifier (required), period (optional: 24h, 7d, 30d, 6mo, 12mo)

get_top_pages Read

Ranked list of most visited pages with view and visitor counts.

Parameters: site_identifier (required), period (optional), limit (optional, max 50)

get_traffic_sources Read

Top referrers driving traffic, excluding self-referrals.

Parameters: site_identifier (required), period (optional), limit (optional, max 50)

get_realtime_visitors Read

Unique visitors active on the site in the last 5 minutes.

Parameters: site_identifier (required)

get_uptime_status Read

Uptime monitor status, uptime percentage, and average response time.

Parameters: site_identifier (required)

list_goals Read

All goals with conversion counts, unique converters, and conversion rates.

Parameters: site_identifier (required), period (optional)

get_funnel_stats Read

Step-by-step conversion data for a specific funnel.

Parameters: site_identifier (required), funnel_identifier (required), period (optional)

manage_annotations Read/Write

List or create annotations on a site.

Parameters: site_identifier (required), action (list or create), text and occurred_at (for create)

support_tickets Read/Write

List, view, create, or reply to support tickets.

Parameters: action (list, show, create, reply), plus action-specific parameters

Permissions and security

The MCP server enforces the same access controls as the GhostlyX dashboard. Your API token determines which sites and actions are available.

Site access You can query any site you own or any site where you are a team member.
Read-only tools Eight of the ten tools are read-only and will never modify your data.
Write tools Annotations and support tickets require write access. Team members with viewer-only roles cannot create or modify data through these tools.
Token scoping API tokens inherit the permissions of the user who created them. Rotating or revoking a token takes effect immediately.
Rate limiting MCP requests share the same rate limits as the REST API. Limits depend on your plan.

Example prompts

Once connected, try asking your AI assistant questions like these. The assistant will call the appropriate MCP tools automatically.

Show me the top 10 pages on example.com for the last 7 days.
What are my total pageviews and unique visitors this month?
Is my site up right now? What is the average response time?
Which traffic sources sent the most visitors in the last 24 hours?
How many real-time visitors are on my site right now?
List all my goals and their conversion rates for the last 30 days.
Show me the checkout funnel drop-off for example.com.
Create an annotation on example.com saying "Launched new homepage".
Open a support ticket about a billing question.

Related documentation

REST API

Query analytics data programmatically with HTTP requests.

MCP Server feature

Learn more about what the MCP server can do.

API tokens

Create and manage your Sanctum API tokens.