# Organiq

> SEO and GEO analysis of your own Google Search Console and GA4 data: summaries, top queries and pages, CTR curve, content decay, cannibalization, opportunities and traffic from AI assistants. Google sign-in; read-only. Interface: an MCP server (Streamable HTTP) plus skills and this documentation. Portuguese and English.

## When to use Organiq

Use it when the user owns or manages a website verified in Google Search Console and asks about its organic search performance: clicks, impressions, CTR and position; which queries or pages grew or declined; pages losing traffic (decay); several pages competing for one query (cannibalization); queries with CTR below the expected for their position (quick wins, striking distance); brand vs non-brand share; the date a drop started and nearby Google updates; sessions coming from AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Claude) via GA4.

Do not use it for: sites the user has not verified in Search Console; competitor data; keyword search volume or backlinks; clicks inside Google AI Overviews / AI Mode (Search Console does not separate them); any write operation (there are none).

## How an agent connects

- MCP endpoint (Streamable HTTP, POST): https://organiqgeo.com/mcp
- Authentication: OAuth 2.1 with PKCE S256. Unauthenticated protected calls return 401 with `WWW-Authenticate: Bearer resource_metadata="https://organiqgeo.com/.well-known/oauth-protected-resource/mcp"`. Client registration: Client ID Metadata Documents (preferred) or Dynamic Client Registration at https://organiqgeo.com/oauth/register. Scopes: mcp:read, mcp:write, offline_access. Alternative for clients without OAuth: `Authorization: Bearer <personal API key gy_live_…>`.
- Public tools that work before sign-in: get_capabilities, get_ctr_benchmark, check_connection.
- Protected resource metadata: https://organiqgeo.com/.well-known/oauth-protected-resource
- Authorization server metadata: https://organiqgeo.com/.well-known/oauth-authorization-server
- Server card: https://organiqgeo.com/.well-known/mcp/server-card.json
- MCP Registry entry: https://registry.modelcontextprotocol.io/v0/servers?search=com.organiqgeo%2Forganiq
- Agent Skills index: https://organiqgeo.com/.well-known/agent-skills/index.json
- Claude Code plugin: plugins/organiq in the product repository (skills + bundled connector)

## Setup guides by client

- Claude (web, desktop, mobile): https://organiqgeo.com/connect/claude (Português: https://organiqgeo.com/pt/connect/claude)
- Claude Code: https://organiqgeo.com/connect/claude-code (Português: https://organiqgeo.com/pt/connect/claude-code)
- Cursor and other MCP clients: https://organiqgeo.com/connect/cursor (Português: https://organiqgeo.com/pt/connect/cursor)
- ChatGPT: https://organiqgeo.com/connect/chatgpt (Português: https://organiqgeo.com/pt/connect/chatgpt)

## Documentation: English / Português

- English (canonical): https://organiqgeo.com/docs · privacy https://organiqgeo.com/privacy · terms https://organiqgeo.com/terms · home https://organiqgeo.com/
- Português: https://organiqgeo.com/pt/docs · privacidade https://organiqgeo.com/pt/privacy · termos https://organiqgeo.com/pt/terms · início https://organiqgeo.com/pt
- Full text for agents (English): https://organiqgeo.com/llms-full.txt
- Support: youssefpmat@gmail.com

## Units and defaults

clicks/impressions: integers; ctr: fraction 0–1 (0.052 = 5.2%); position: impression-weighted average, lower is better; dates: yyyy-mm-dd. Default period: 28 days ending on the last synced date (Search Console lags about 3 days). Default comparison: the previous window of the same length. Every response states the period and comparison used.

## Example questions

- How did example.com do in the last 28 days compared with the previous 28?
- Which queries grew the most and which lost clicks last month?
- Which pages are decaying compared with six months ago?
- Where are we cannibalizing: several pages ranking for the same query?
- Give me quick wins: queries with CTR below the expected for their position.
- How many sessions came from ChatGPT, Perplexity and Gemini this month?

## Tools (18)

### get_capabilities (public)

What Organiq provides. Returns a factual overview of this connector: what data it holds (Google Search Console synced daily into Organiq, plus GA4 referral sessions from AI assistants), the list of tools with when to use each, units, default periods, how to connect an account (OAuth or API key), rate limits and example questions. Works without signing in. Use it first when you do not know what this server can answer. / Visão geral factual do conector, sem login: dados, ferramentas, unidades, como conectar, limites.

Parameters: language.

### get_ctr_benchmark (public)

Generic CTR-by-position benchmark. Returns the generic organic click-through-rate curve by Google position (1–20, fraction 0–1) used by score_opportunities and find_page_poaching_opportunities as the fallback when a property lacks its own volume, optionally interpolated for a fractional position. No account needed; no property data involved. Use it to estimate expected clicks for a position or to explain a CTR gap. / Curva genérica de CTR por posição, sem login.

Parameters: position, impressions.

### check_connection (public)

Connection status. Reports whether this request is authenticated and, if so, which Organiq account it uses (name, plan, how it authenticated), how many Search Console properties are available with their data coverage, and what is missing (no account, no properties, no GA4) with the URL that resolves each gap. Without credentials it explains how to connect. Use it when a tool returned unauthorized/site_not_found or before a first analysis. / Diz se há conta, propriedades, plano e o que falta, com a URL para resolver.

Parameters: none.

### list_sites

Properties in the account. Lists the Search Console properties synced for the signed-in account: id, siteUrl (Search Console format), displayName, tags, branded_terms (used by the brand filter), whether GA4/Bing are mapped and the data coverage (dataFrom/dataTo, web search). Use it first when you do not know the exact name of a site or need the date range available. Default: visible properties only. / Propriedades da conta com cobertura de dados.

Parameters: includeHidden.

### get_site_summary

Property summary. Totals of clicks, impressions, CTR and average position for one property over the period, with the comparison period and the change (absolute, Pct as fraction, ctrPoints in percentage points, position difference where negative means improvement). Accepts all filters (country, device, brand, page, query). Start here for "how is site X doing". / Resumo da propriedade com comparação.

Parameters: site, days, startDate, endDate, compare, searchType, country, device, brand, pageContains, query.

### query_top_queries

Top queries. Search queries of one property over the period, aggregated and sorted. Use for "what people search to find us", growth/decline lists and ranking changes. Each row has clicks, impressions, ctr, position for the period and, with a comparison, prevClicks/prevImpressions/prevCtr/prevPosition plus clicksChange/clicksChangePct/positionChange (keys present in only one period show zeros in the other). sort: clicks (default), impressions, ctr, position (lowest first), growth (largest click gain vs comparison first) or decline (largest loss first). For ctr/position use minImpressions >= 20 to avoid noise. / Queries da propriedade, agregadas e ordenadas.

Parameters: site, days, startDate, endDate, compare, searchType, country, device, brand, pageContains, query, limit, sort, minImpressions.

### query_top_pages

Top pages. Pages (URLs) of one property over the period, aggregated and sorted. Use for best/worst pages and pages that gained or lost clicks. Each row has clicks, impressions, ctr, position for the period and, with a comparison, prevClicks/prevImpressions/prevCtr/prevPosition plus clicksChange/clicksChangePct/positionChange (keys present in only one period show zeros in the other). sort: clicks (default), impressions, ctr, position (lowest first), growth (largest click gain vs comparison first) or decline (largest loss first). For ctr/position use minImpressions >= 20 to avoid noise. / Páginas da propriedade, agregadas e ordenadas.

Parameters: site, days, startDate, endDate, compare, searchType, country, device, brand, pageContains, query, limit, sort, minImpressions.

### query_countries

By country. Countries (ISO-3166-1 alpha-3, lowercase, e.g. bra) of one property over the period. Each row has clicks, impressions, ctr, position for the period and, with a comparison, prevClicks/prevImpressions/prevCtr/prevPosition plus clicksChange/clicksChangePct/positionChange (keys present in only one period show zeros in the other). sort: clicks (default), impressions, ctr, position (lowest first), growth (largest click gain vs comparison first) or decline (largest loss first). For ctr/position use minImpressions >= 20 to avoid noise. / Por país.

Parameters: site, days, startDate, endDate, compare, searchType, country, device, brand, pageContains, query, limit, sort, minImpressions.

### query_devices

By device. Devices (MOBILE, DESKTOP, TABLET) of one property over the period. Each row has clicks, impressions, ctr, position for the period and, with a comparison, prevClicks/prevImpressions/prevCtr/prevPosition plus clicksChange/clicksChangePct/positionChange (keys present in only one period show zeros in the other). sort: clicks (default), impressions, ctr, position (lowest first), growth (largest click gain vs comparison first) or decline (largest loss first). For ctr/position use minImpressions >= 20 to avoid noise. / Por dispositivo.

Parameters: site, days, startDate, endDate, compare, searchType, country, device, brand, pageContains, query, limit, sort, minImpressions.

### get_timeseries

Time series. Clicks, impressions, CTR and position per day, week (Monday as key) or month (yyyy-mm) over the period, with filters. Use for trend, seasonality and to locate the date of a drop. Days without data are omitted. / Série temporal por dia, semana ou mês.

Parameters: site, days, startDate, endDate, searchType, country, device, brand, pageContains, query, granularity.

### get_breakdown

Brand split and position bands. Splits the period's traffic into branded/nonBranded (by the property's branded_terms) and into position bands (1-3, 4-10, 11-20, 21+) with impressions and clicks per band, plus queryCount. Position of each query = impression-weighted average over the period. Use for "how much of our traffic is brand" and "how much sits on page 2". / Marca × sem marca e faixas de posição.

Parameters: site, days, startDate, endDate, searchType, country, device, brand, pageContains, query.

### get_annotations

Annotations. Events annotated in the period for the property and globally: deploys, content changes, manual notes and Google algorithm updates (category "algo_update"). Use to correlate drops or gains with causes. Default: last 90 days. / Anotações e algo updates do período.

Parameters: site, days, startDate, endDate.

### get_ai_traffic

Traffic from AI assistants (GA4). Referral sessions from AI assistants (chatgpt.com, perplexity.ai, gemini, copilot, claude…) according to GA4 (dimension ai_source): per source (sessions, activeUsers, engagedSessions, keyEvents) for the period and the comparison, totals and daily series. site also accepts "all" for the whole account. hasGa4=false means the property has no GA4 mapped. Limitation: Search Console does not separate clicks from AI Overviews / AI Mode; only referral traffic is measurable. / Sessões vindas de IAs segundo o GA4.

Parameters: site, days, startDate, endDate, compare.

### get_ctr_curve

Own CTR curve vs benchmark. The property's real CTR by position (bucket = round(position), 1–20, impression-weighted) compared with the generic benchmark (31.7% at position 1 … 18.6% at 3 … 2.0% at 10). deltaPoints in percentage points (negative = below expected: likely title/meta problem); reliable = bucket with enough impressions. Use to find where titles underperform. / Curva de CTR própria × benchmark.

Parameters: site, days, startDate, endDate, searchType, country, device, brand, pageContains, query, minImpressions.

### find_decaying_content

Decaying content. Pages (or queries) that lost clicks between a BASELINE and the RECENT period. Recent = days/startDate/endDate; baseline = compare (previous = window before, year = one year earlier) or explicit comparisonStartDate/comparisonEndDate (for slow decay compare with 6–12 months ago). Classifies the drop: severe > 50%, moderate 20–50%, mild < 20%; sorted by absolute clicks lost; pattern hints the diagnosis (position_slipped, impressions_collapsed, ctr_dropped, disappeared, mixed). Use for "which pages are dying" and refresh candidates. / Conteúdo em decaimento.

Parameters: site, days, startDate, endDate, compare, searchType, country, device, brand, pageContains, query, comparisonStartDate, comparisonEndDate, dimension, minBaselineClicks, limit.

### analyze_cannibalization

Query cannibalization. Queries where 2+ pages of the property compete for the same search in the period. Per cluster: totals, Shannon entropy of impressions across pages (bits; higher = more even split = worse; level high >= 1.5, medium >= 1.0), normalized (0–1), winner (most clicks; tie: best position) and the contenders with clicks/impressions/ctr/position/impressionShare. Sorted by entropy and impressions. Protocol/host/hash variants of one URL are canonical hygiene, not cannibalization; brand + home + deep page is usually sitelinks. Use when asked which page should rank for a keyword. / Canibalização de queries.

Parameters: site, days, startDate, endDate, searchType, country, device, brand, pageContains, query, minImpressions, minPages, limit.

### score_opportunities

Opportunity score (CTR gap). Queries between minPosition and maxPosition whose CTR is below the expected CTR for their position. expectedCtr comes from the property's own curve (ctrSource "own", when the bucket has volume) or from the benchmark; ctrGap = expected − ctr (fraction); lostClicks = impressions × gap; score 0–100 log-normalized by the largest lostClicks (level high >= 80, medium >= 60). Use for title/meta-description quick wins. / Oportunidades por CTR abaixo do esperado.

Parameters: site, days, startDate, endDate, searchType, country, device, brand, pageContains, query, minImpressions, minPosition, maxPosition, limit.

### find_page_poaching_opportunities

Striking distance (page poaching). Queries just outside the top (default positions 4–20) with the estimated click gain if they reached the CTR of the target position (default 3 → 18.6% benchmark, or the property's own CTR at that position when it has volume: see ctrSource). estimatedGain = max(0, round(impressions × (targetCtr − ctr))). Sorted by impressions (default) or by gain. Use for "what is close to page one / top 3". / Queries perto do topo com ganho estimado.

Parameters: site, days, startDate, endDate, searchType, country, device, brand, pageContains, query, minPosition, maxPosition, targetPosition, minImpressions, sort, limit.

## Errors

Every error is JSON: `{ "error": { "code", "message", "nextStep", "docsUrl" } }`. Codes: unauthorized (401 at HTTP level when no or invalid credential), insufficient_scope (403), site_not_found, no_data, invalid_argument, plan_limit (402: the account plan does not cover the request, e.g. history older than the plan window; docsUrl = plans page), rate_limited (includes retryAfterSeconds), internal.

## Rate limits

Per account: 60 calls per minute and 1,000 per hour (rate_limited tells which window and how many seconds to wait). Per IP: 120 requests per minute on /mcp, 60 on /oauth/*.

## OAuth flow summary

1. Client calls a protected tool without a token → 401 with resource_metadata.
2. Client reads https://organiqgeo.com/.well-known/oauth-protected-resource/mcp → authorization_servers = [https://organiqgeo.com] → https://organiqgeo.com/.well-known/oauth-authorization-server.
3. Client identifies itself with its Client ID Metadata Document (client_id = HTTPS URL) or registers at https://organiqgeo.com/oauth/register.
4. https://organiqgeo.com/oauth/authorize with PKCE S256, scope and resource=https://organiqgeo.com/mcp; the user signs in with Google and approves on the Organiq consent screen (only accounts with at least one Search Console property can approve).
5. https://organiqgeo.com/oauth/token exchanges the code; refresh tokens rotate on every use; access tokens last 1 hour.

## Skills

- ai-traffic: Measure and interpret traffic coming from AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Claude) and conversational search queries using GA4 and Google Search Console data through the Organiq MCP server (get_ai_traffic, query_top_queries, get_timeseries). Use when the user asks about GEO, AI traffic, LLM referrals, how much traffic comes from ChatGPT or Perplexity, AI Overviews impact, or question-style queries.
- cannibalization: Detect and resolve keyword cannibalization in Google Search Console data through the Organiq MCP server (analyze_cannibalization, query_top_pages). Use when the user mentions cannibalization, several pages ranking for one query, pages competing for the same keyword, or asks which page should rank for a term.
- content-decay: Find, triage and build a recovery plan for decaying content in Google Search Console data through the Organiq MCP server (find_decaying_content, get_timeseries, query_top_queries, get_annotations). Use when the user asks about pages losing traffic, declining clicks, content refresh candidates, which pages are dying, or why a page dropped.
- quick-wins: Find title/meta-description quick wins in a property's Google Search Console data through the Organiq MCP server (score_opportunities, find_page_poaching_opportunities, get_ctr_curve, get_breakdown). Use when the user asks for quick wins, low-hanging fruit, queries with CTR below expected, striking-distance keywords, what to optimize first this week, or pages close to page one.
- weekly-report: Produce a weekly organic-search report for a property from Google Search Console and GA4 data through the Organiq MCP server (get_site_summary, query_top_queries, query_top_pages, get_annotations, get_ai_traffic). Use when the user asks for a weekly or monthly SEO report, a status update on a site, what changed this week, or a summary for a client.