GeoGenie MCP

GeoGenie MCP is GeoGenie's official Model Context Protocol (MCP) server. It lets AI assistants such as Claude, ChatGPT, and Cursor read your GeoGenie workspace data — metrics, citations, prompts, topics, personas, and ActionsGenie content — directly inside the tools you already use. Access is read-only and scoped to the workspaces you choose when you create a token.

How it works

You create an MCP integration token in the GeoGenie Console. Your MCP client connects to GeoGenie's hosted server at https://mcp.geogenie.ai/mcp and authenticates with that token. The server exposes a set of read-only tools that return JSON from your workspace — the same data you see in MonitoringGenie (including Prompt Monitoring and Prompt Details), CitationsGenie, and ActionsGenie.

Tokens are scoped to one or more workspaces and carry the mcp:read scope. You can revoke a token at any time from the Console without affecting other integrations.

Prerequisites

A GeoGenie account with at least one workspace configured
An MCP-compatible client (for example Cursor, Claude Desktop, or ChatGPT with MCP support)
Permission to create integration tokens in your organization's Console

Create an MCP token

GeoGenie generates your connection details in the Console, including a one-time API token:

Open the GeoGenie Console and go to Settings → Integrations.
Under MCP Integrations, click Create token.
Give the token a name and select one or more workspaces it should access.
Copy the token when it is shown — it starts with gg_mcp_ and is only displayed once. Store it securely.
Use Copy setup details to copy the full connection block for your MCP client.

The setup details include everything most OAuth-capable clients need:

MCP Server URL: https://mcp.geogenie.ai/mcp OAuth Token URL: https://mcp.geogenie.ai/mcp/oauth/token OAuth Grant Type: client_credentials OAuth Client ID: geogenie-mcp (or any string) OAuth Scope: mcp:read OAuth Client Secret (store securely): gg_mcp_<your-token>

Connect your MCP client

Cursor

Add GeoGenie as a remote MCP server in your Cursor MCP settings. Use the server URL and pass your token as a Bearer header:

{ "mcpServers": { "geogenie": { "url": "https://mcp.geogenie.ai/mcp", "headers": { "Authorization": "Bearer gg_mcp_<your-token>" } } } }

Replace gg_mcp_<your-token> with the token you copied from the Console. Restart Cursor or reload MCP servers after saving.

OAuth-capable clients

Clients that support OAuth 2.0 can use the client_credentials grant against the token URL. Send your gg_mcp_... token as the client secret:

POST https://mcp.geogenie.ai/mcp/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&scope=mcp:read&client_secret=gg_mcp_<your-token>

The response includes a short-lived access token (typically three hours). Use that token in the Authorization: Bearer header for MCP requests. OAuth discovery metadata is available at https://mcp.geogenie.ai/mcp/.well-known/oauth-authorization-server.

Direct token (simple mode)

Many clients also accept your gg_mcp_... token directly as a Bearer token without a separate OAuth exchange. This is the simplest option for local tools like Cursor when you do not need rotating access tokens.

Available tools

Once connected, your AI assistant can call these read-only tools. Most tools accept an optional workspace_id; if omitted, the token's primary workspace is used.

Workspace & context

list_workspaces — list all workspaces your token can access, with summaries
get_workspace_summary — workspace name, brand, prompt counts, and overview
get_workspace_context — alias for workspace summary
get_workspace_context_data — full ContextGenie bundle: workspace, topics, personas, and competitors
list_topics — topics configured for the workspace
list_personas — personas configured for the workspace

Monitoring & citations

list_prompts — basic list of monitoring prompts for the workspace
get_prompts_performance — prompt monitoring table data grouped by topic, with per-prompt metrics (share of voice, visibility score, citation share, execution count). Same data as the Prompt Monitoring page. Defaults to the last 7 days. Optional filters: start_date, end_date, source (chatgpt, perplexity, gemini, copilot, aio), and branded_filter (branded or unbranded)
get_prompt_details — full prompt detail bundle for a single prompt: summary, executions, citations, and time-series metrics. Same data as the Prompt Details page. Requires prompt_id. Defaults to the last 7 days. Optional filters: start_date, end_date, and platform (chatgpt, perplexity, gemini, copilot, aio)
get_filter_options — available dashboard filters (topics, tags)
get_overall_metrics — overall metrics (defaults to the last 30 days)
get_dashboard_metrics — dashboard metrics (defaults to the last 30 days)
search_citations — search citation URLs with optional date, topic, platform, and tag filters

ActionsGenie content

list_generated_content — list generated briefs, articles, and YouTube metadata
get_generated_brief — retrieve the full brief payload for a specific job ID

Example prompts you can ask your assistant: "List my GeoGenie workspaces", "Show dashboard metrics for the last 30 days", "Show prompt performance for the last week", "Get details for prompt abc-123", "Search citations mentioning example.com", or "Get the content brief for job abc-123".

Security

Tokens are read-only — MCP tools cannot create, update, or delete GeoGenie data.
Each token is scoped to the workspaces you select at creation time. Requests for other workspaces are rejected.
Revoke a token from Settings → Integrations if it is compromised or no longer needed.
Treat your gg_mcp_... token like a password. Do not commit it to source control or share it in public channels.

Troubleshooting

Authentication failed — confirm the token starts with gg_mcp_, has not been revoked, and is passed as Authorization: Bearer ...
Workspace access denied — the token may not include the workspace you requested. Create a new token with the correct workspace scope, or pass a workspace_id that your token can access.
OAuth token expired — request a new access token from the OAuth token URL, or use direct Bearer mode with your gg_mcp_... token.
Client cannot connect — verify the server URL is https://mcp.geogenie.ai/mcp (with no trailing slash issues in your client config) and that your network allows outbound HTTPS.
Prompt access denied — get_prompt_details only works for prompts in workspaces your token can access. Use get_prompts_performance or list_prompts to find valid prompt IDs first.
Tools return empty data — ensure the workspace has prompts, citations, or generated content configured in the Console before expecting results.