GEOly MCP User Guide

GEOly MCP (Model Context Protocol) connects authorized GEOly data and actions to AI clients that support remote MCP. After connecting, you can ask Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, or Codex about brand monitoring, prompts, competitors, citations, sources, sentiment, and GEO audits. The three free public-source tools are available when Source read permission is granted. Public entity, locale, and platform discovery tools do not consume MCP Credits, but they require Grow or above plus Public data read permission; paid public industry intelligence has the same access requirements and consumes MCP Credits.

This guide explains the current OAuth connection flow, permissions, client setup, Agent Skill, MCP Credits, and the boundaries you should understand before using write actions.

Before you connect: MCP, Agent Skill, and Sidekick

These features work together but solve different problems:

• MCP is the secure connection layer. It exposes only the organizations, resources, and actions approved during OAuth.
• Agent Skill teaches a compatible AI client how to choose GEOly tools, resolve scope, and interpret metrics. It does not add permissions or plan access.
• Sidekick is GEOly's in-product contextual assistant. It works inside supported GEOly pages and is separate from external MCP clients.

Connect in about three minutes

1. In GEOly, open MCP & Tools → MCP from the left navigation and copy the remote server URL: https://app.geoly.ai/api/mcp.
2. Add the server to your preferred MCP client using one of the configurations below.
3. Start the connection or call the GEOly server for the first time.
4. Complete OAuth in the browser: choose an organization, approve the required read resources, and grant write access only when needed.
5. Return to the client and ask it to list your available GEOly organizations or brands.

OAuth is the recommended setup. Legacy geom_ tokens may remain available for read-only compatibility in existing installations, but they are not the setup method described in this guide.

Client setup

Claude Code

claude mcp add --transport http geoly "https://app.geoly.ai/api/mcp"

Then run /mcp in Claude Code, select geoly, and complete OAuth.

Cursor

Add this configuration to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "geoly": {
      "url": "https://app.geoly.ai/api/mcp"
    }
  }
}

Save the file, reload Cursor, enable the server, and complete OAuth when prompted.

Claude Desktop

If your Claude Desktop version supports native Connectors, add the remote URL directly. For versions that require a local bridge, use:

{
  "mcpServers": {
    "geoly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.geoly.ai/api/mcp"]
    }
  }
}

Restart Claude Desktop after saving the configuration, then complete OAuth.

VS Code

Create or update .vscode/mcp.json:

{
  "servers": {
    "geoly": {
      "type": "http",
      "url": "https://app.geoly.ai/api/mcp"
    }
  }
}

Start the server from VS Code and complete OAuth.

Windsurf

Add this configuration to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "geoly": {
      "serverUrl": "https://app.geoly.ai/api/mcp"
    }
  }
}

Save the file, reload Windsurf, and complete OAuth on the first call.

Codex

Install the official GEOly plugin, then restart Codex if requested:

codex plugin marketplace add geoly-ai/codex-plugins
codex plugin add geoly-mcp@geoly

The first GEOly call opens OAuth in the browser. If the plugin already exists, update the marketplace first:

codex plugin marketplace upgrade geoly

OAuth permissions and scope

During authorization, GEOly asks you to choose the data and actions the client may use.

Organization scope

• Choose one organization when the client needs read and write access to a specific workspace.
• Choosing all organizations is useful for broad read-only discovery, but write actions are disabled to prevent ambiguous changes.
• In a multi-brand organization, resolve the brand before requesting detailed analysis or any write action.

Resource permissions

Read permissions may cover brands, prompts, competitors, citations, analytics, audits, sources, and public data. Write permissions are separate and should be granted only for resources the workflow must change. Agent Readiness tools are user-scoped, read-only capabilities that remain available to a valid MCP authorization and can only access that user's own scans; they are not controlled by the brand resource-permission matrix.

The client only sees tools allowed by the selected organization, plan, account permissions, and OAuth scope. A missing tool does not automatically mean the connection failed.

Write safety

Before a write action, the AI client should show the target organization, brand, resource, and intended change. Review those details before approving. Avoid relying on a guessed brand or organization from conversation context.

Plan and data boundaries

GEOly MCP serves several data classes:

Basic includes no public discovery or paid public-industry access. Your own monitoring data, approved write actions, organization/brand navigation, quota checks, and the three free public-source tools (when Source read permission is granted) remain available.

MCP Credits: what customers need to know

MCP Credits are separate from AI Credits. AI Credits support AI analysis or generation inside GEOly; MCP Credits apply only to paid public industry intelligence used through MCP, the GEOly CLI, and future eligible API access.

Plan allowance

The allowance is shared by the organization and resets on a monthly quota window anchored to the subscription date. The exact reset time is returned by get_quota as resets_at; unused credits do not roll over, and adding seats does not increase the pool.

How charging works

Paid tools charge by the number of results actually returned multiplied by the tool rate:

A KPI or summary object counts as one returned result. A list of 20 rows at the advanced rate costs 60 credits. If a request reserves more than the final result, the unused portion is refunded automatically.

System errors and timeouts are not charged. An empty, insufficient-sample, or minimum-locale result may incur a one-result minimum fee when the tool still completes the query. Each call is capped at 2,500 credits; a request above the cap is rejected without charge. Only tools explicitly marked as heavy use the documented multiplier, such as supported shopping analysis over more than 90 days.

Use the free get_quota capability to see used credits, remaining credits, and the reset time. Paid responses include a _quota receipt with the current call cost and remaining balance.

When the pool is exhausted, your own monitoring data and all other free tools keep working. Only paid public industry intelligence pauses until the next reset or a plan upgrade.

Install the Agent Skill

The MCP connection controls access; the Agent Skill improves how a compatible AI client works with that access. Install it from the GEOly MCP settings page or through the official Codex plugin when available.

The skill helps the client:

• resolve the organization and brand before analysis;
• select the correct tool for monitoring versus public industry research;
• use the correct platform, locale, and time window;
• distinguish mentions, citations, sentiment, AIGVR, and Share of Model;
• avoid unsupported causal claims;
• request confirmation before write actions.

It does not unlock tools, increase credits, or override OAuth and plan restrictions.

What you can ask GEOly MCP to do

Recommended workflows

1. Weekly brand review

Ask the client to confirm the brand, platform, and seven- or thirty-day window. Review the headline trend, prompt changes, competitor movement, and citation sources. End with a short verification list rather than an unsupported explanation of cause.

2. Content and citation opportunity review

Identify prompts where the brand is absent or weak, inspect the sources cited by the AI answers, and compare those sources with your current content coverage. Use this as evidence for content or digital PR research; do not describe citations as website traffic or confirmed conversions.

3. Public market research

Resolve the public entity and locale first, check available platforms, then request a bounded number of rows. Start with a small result limit and expand only if the first result answers the question. This keeps MCP Credit usage predictable.

Interpreting results correctly

• A mention means the brand appeared in the captured AI response.
• A citation means the response referenced a source; it does not prove a user clicked or visited that source.
• Sentiment describes the analyzed response text and should be reviewed with the underlying evidence.
• A change between periods is correlation, not automatic proof that a specific page edit, campaign, or competitor action caused it.
• Public industry data and your private monitored-brand data have different scopes and should not be combined without stating that distinction.

Troubleshooting and FAQ

Why did OAuth not open?

Start or call the GEOly MCP server from the client. Claude Desktop setups using the local bridge must be able to run npx mcp-remote. Reload or restart the client after saving the configuration.

Why do I see only a few tools?

Check the selected organization, OAuth resources, account role, and plan. The server exposes only tools available within all four boundaries.

Why are write tools missing?

Write permission may not have been granted. Write tools are also disabled when OAuth covers all organizations; reconnect and choose one explicit organization if the workflow requires changes.

Why did the client query the wrong brand?

In a multi-brand or multi-organization setup, list organizations and brands first. Never approve a write until the exact target is shown.

Why are some public industry tools unavailable?

The three free public-source tools require Source read permission. Public discovery tools do not consume MCP Credits, but they still require Grow or above plus Public data read permission; paid public industry intelligence has the same access requirements and also consumes MCP Credits.

Which operations consume MCP Credits?

Only paid public industry intelligence. Your own monitoring data, approved write actions, quota checks, and available free tools do not consume MCP Credits. Public discovery is zero-credit but still requires Grow or above plus Public data read permission.

Do calls about my own brand consume MCP Credits?

No. Visibility, prompt records, citations, tracked competitors, platform coverage, sentiment, and audits for your organization are included in the subscription.

Are MCP Credits and AI Credits the same?

No. They are separate pools for different product capabilities.

What happens when MCP Credits run out?

Free capabilities continue to work. Paid public industry intelligence pauses until the next subscription reset or an eligible plan upgrade.

How do I check usage?

Call get_quota. Each paid response also includes a _quota usage receipt.

Why does Codex show outdated tools or instructions?

Run codex plugin marketplace upgrade geoly, reinstall or update geoly-mcp@geoly, and restart Codex. Reconnect OAuth if the authorization is stale.

Why is the MCP connected but the AI still chooses the wrong action?

State the goal, organization or brand, platform, locale, and time window. Install the Agent Skill for better tool selection and metric interpretation; remember that the skill does not add permissions.

A reliable prompt format

Include five elements whenever possible:

1. Goal — what decision you need to make.
2. Scope — organization and brand, or public entity and locale.
3. Platform — such as ChatGPT, Perplexity, Gemini, Google AI Mode, Copilot, or Google AI Overview when available for the selected scope.
4. Time window — exact dates or a defined recent period.
5. Output — table, summary, evidence list, or approved write action.

Example: “For the selected brand, compare ChatGPT visibility over the last 30 days with the previous 30 days. Show the five prompts with the largest decline, the cited sources in those responses, and a verification checklist. Do not infer causality without evidence.”

Final checklist

• Use OAuth instead of creating a new static token configuration.
• Confirm organization, brand, platform, locale, and time window.
• Grant the minimum necessary read and write permissions.
• Keep private monitoring and public industry data clearly separated.
• Check get_quota before large paid research requests.
• Treat citations as evidence, not referral traffic.
• Require explicit confirmation for every write action.