Skip to content

Use Moderok from AI agents ​

Moderok runs a remote MCP server at:

txt
https://app.moderok.dev/api/mcp

Connect Claude, ChatGPT, Cursor, VS Code or any other MCP client and your agent can read your extension analytics: active users, installs and uninstalls, Trends metrics, custom events, raw event logs, captured errors, and setup instructions with your app key. It can answer questions like "why did installs drop last week?" or "which error is hitting the most users?" without you copying numbers out of the dashboard.

The server is read-only. No tool can change anything in your organization.

You connect by signing in to Moderok from the AI app. There is no token to copy. Scripts and CI jobs, which cannot sign in, use an API token instead.

Connect ​

Claude ​

Add to Claude

  1. Click Add to Claude above, or in the dashboard under Organization settings → AI tools. Claude opens Add custom connector with the name and URL filled in. To add it by hand, go to Customize → Connectors, click Add custom connector, and enter Moderok and https://app.moderok.dev/api/mcp.
  2. If the dialog asks about sign-in, choose Sign in now and keep Use Claude's published identity. Click Add.
  3. Sign in to Moderok and click Allow.

One connector covers claude.ai, Claude Desktop, the Claude mobile apps, and Claude Code when Claude Code is logged in with your claude.ai account.

On a Team or Enterprise plan, only an Owner can add a custom connector. Ask an Owner to add Moderok under Organization settings → Connectors. Each person then clicks Connect on it under Customize → Connectors and signs in with their own Moderok account. On Claude's Free plan you can add one custom connector.

What happens when you sign in ​

Every app on this page signs in the same way:

  1. Your browser opens app.moderok.dev. If you are signed out, click Continue with Google or Continue with GitHub.
  2. Moderok asks you to connect the app, for example Connect Claude to Moderok. Under Read-only access to, pick the organization the app may read. See Choose an organization.
  3. Check the app name and where it will return you (a website, or this computer), then click Allow. The browser returns to the app, which is now connected. Cancel connects nothing.

The app stays connected without asking again. Its access token lasts an hour and renews on its own. You sign in again only when the connection ends.

Moderok recognizes Claude, Claude Code, ChatGPT, Cursor and VS Code, and apps that only return to your own computer. For any other app the page shows its web address instead of a name and marks it Not a known AI app. Only owners and admins can allow those.

Claude Code ​

If Claude Code is logged in with your claude.ai account, the Claude connector is already there: run /mcp and look for claude.ai Moderok.

With an API key, Amazon Bedrock or Google Vertex AI, add the server yourself:

sh
claude mcp add --transport http --scope user moderok https://app.moderok.dev/api/mcp

Then run /mcp in Claude Code, select moderok, and choose Authenticate. From a shell, claude mcp login moderok does the same. --scope user makes the server available in every project.

Cursor ​

Add to Cursor, or add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

json
{
  "mcpServers": {
    "moderok": {
      "url": "https://app.moderok.dev/api/mcp"
    }
  }
}

Then, in Cursor's MCP settings, click Needs login next to moderok and sign in.

VS Code ​

Add to VS Code, or run MCP: Open User Configuration from the Command Palette and add:

json
{
  "servers": {
    "moderok": {
      "type": "http",
      "url": "https://app.moderok.dev/api/mcp"
    }
  }
}

For one project only, use MCP: Open Workspace Folder MCP Configuration, which opens .vscode/mcp.json. VS Code asks you to sign in to Moderok the first time the server starts. Accept, then finish in the browser.

ChatGPT ​

  1. Go to ChatGPT Plugins, select +, then Add custom MCP server.
  2. Name it Moderok. Under Connection, enter https://app.moderok.dev/api/mcp.
  3. Set authentication to OAuth, review the warning, and select I understand and want to continue.
  4. Select Create as a plugin, then sign in to Moderok when ChatGPT asks.

Codex ​

sh
codex mcp add moderok --url https://app.moderok.dev/api/mcp
codex mcp login moderok

The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share this configuration.

Other clients ​

Any client that supports MCP sign-in (OAuth) connects with the URL alone. Add https://app.moderok.dev/api/mcp as a remote server (Streamable HTTP) and sign in when the client asks. A client that can only send a fixed header needs an API token.

For client developers: the server publishes its protected resource metadata at https://app.moderok.dev/.well-known/oauth-protected-resource/api/mcp. Sign-in uses the authorization code flow with PKCE (S256), and clients identify themselves with a client ID metadata document or dynamic client registration. The server is stateless and answers every request with plain JSON over POST. It does not open server-sent event streams: GET returns 405, and subscriptions/listen answers "method not found" because the tool list never changes while the server runs. Send one JSON-RPC message per request; batches are refused with 400. It negotiates protocol revisions 2024-11-05 through 2025-11-25, and 2026-07-28.

Choose an organization ​

Each connection reads one organization: the one you pick on the sign-in page. The organization you have open in the dashboard is selected first. On a Claude Team or Enterprise plan, the Owner adds the connector once and each person still picks their own Moderok organization.

To read a different organization, sign in again and pick it. In Claude Code, run /mcp, select moderok, choose Clear authentication, then Authenticate. In other apps, disconnect Moderok and connect it again.

Every member of an organization can connect Claude, Claude Code, ChatGPT, Cursor, VS Code, and apps that return to their own computer. An app Moderok does not recognize needs an owner or admin: members see Ask an owner or admin to connect this app instead of Allow.

Manage connections ​

Open Organization settings → AI tools in the dashboard. Connected apps lists each connection with the app, when it was last used, and Revoke. Members see their own connections. Owners and admins see everyone's, with the person who connected each one.

Click Revoke, then Revoke access. The connection ends at once: the app's next request fails and it asks you to sign in again. Removing Moderok from an app does not end the connection in Moderok, so revoke it here too.

A connection also ends on its own:

  • 365 days after you connect, or 90 days for an app Moderok does not recognize. The list shows Expires and the date during the last 14 days.
  • When the app has not connected for 90 days.
  • When you leave the organization or are removed from it.

Scripts and CI ​

Anything that cannot open a browser to sign in, such as a CI job, a cron script or curl, uses an organization API token. claude -p and the Claude Agent SDK can use a server you signed in to from an interactive session first (/mcp or claude mcp login moderok). Where nobody can sign in, use a token.

Create an API token ​

Owners and admins create API tokens:

  1. In Organization settings → AI tools, open API tokens.
  2. Name the token after where it will run, such as GitHub Actions, and click Create token.
  3. Copy the token. It starts with mkp_ and is shown once. Moderok keeps only a hash of it, so it cannot be shown again. If you lose it, create a new one.

A token reads every extension in the organization it was created in, and nothing outside it. The token list shows each token's name, prefix, who created it, when, and when it was last used.

Send the token as Authorization: Bearer mkp_…. Replace mkp_… in the examples with your token.

Claude Code:

sh
claude mcp add --transport http --scope user moderok https://app.moderok.dev/api/mcp \
  --header "Authorization: Bearer mkp_…"

A checked-in .mcp.json, with the token read from each environment:

json
{
  "mcpServers": {
    "moderok": {
      "type": "http",
      "url": "https://app.moderok.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MODEROK_TOKEN}"
      }
    }
  }
}

curl:

sh
curl -s https://app.moderok.dev/api/mcp \
  -H "Authorization: Bearer $MODEROK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Treat a token like a password. Keep it in an environment variable or a secret store, not in a file you commit, and give each machine its own token so you can revoke one without breaking the others.

Troubleshooting ​

Moderok is missing in Claude desktop Code sessions ​

Code sessions started from the Claude desktop app may not load a server saved at local scope, which is the default for claude mcp add. Use the Claude connector, which the desktop app passes to its Code sessions, or add the server with --scope user.

Moving from an API token header ​

If you added Moderok to Claude Code with an Authorization header, remove that entry:

sh
claude mcp remove moderok -s local

Use -s user or -s project instead if you added it at that scope. Then use the Claude connector or the Claude Code command. A server you add in Claude Code takes precedence over a claude.ai connector with the same URL, and /mcp lists the connector as hidden until you remove the server.

In other clients, delete the headers entry from the Moderok config and connect again. Revoke the old token under API tokens if nothing else uses it.

Signing in again ​

The app asks you to sign in again when a connection ends. To do it yourself:

  • Claude Code: run /mcp, select moderok, and choose Re-authenticate, or run claude mcp login moderok.
  • Codex: run codex mcp login moderok.
  • Other apps: disconnect Moderok and connect it again.

"Ask an owner or admin to connect this app" ​

Moderok does not recognize the app, and only owners and admins can allow those. Ask one of them to connect it, or use one of the apps above.

ChatGPT has no option to add an MCP server ​

Your ChatGPT account or workspace settings decide whether you can add custom MCP servers. On a workspace, ask its admin.

Tools ​

ToolWhat it returns
list_extensionsEvery extension in the organization: id, name, Chrome extension id, whether it reports through @moderok/sdk or the WXT provider, and when its last event arrived. Agents start here; every other tool takes an extensionId from this list.
get_overviewHeadline numbers for one extension over the last 7, 30 or 90 complete days: active users (latest complete day, trailing 7 days, trailing 28 days), installs, uninstalls, net installs, captured errors, custom events named like errors, and the top 10 custom events, each compared with the window before it.
get_trendOne Trends metric as a daily series (hourly for windows of two days or less) with average, peak, and the change from the previous window. Daily series list every day of the window, with 0 on days without data. Metrics: dau, engaged, wau, mau, installs, updates, uninstalls, churn, tenure, errors.
list_event_namesThe custom and automatic event names the extension sent in a window, with counts: the 500 most frequent names, and a flag when there are more.
get_event_seriesDaily counts for up to 5 event names, so an agent can compare them.
search_logsRaw events, newest first, with their properties. Filter by exact event name and by text that matches the event name, anonymous user id, or any property value. Up to 100 events per call.
get_errorsCaptured errors grouped by message: count, distinct users, first and last seen, and the properties of the latest occurrence, including the stack.
get_setup_instructionsInstall and initialization steps for @moderok/sdk or WXT, with the extension's app key filled in.

Windows are in UTC and up to 180 days long. get_overview takes a preset range. get_trend, list_event_names, get_event_series and get_errors take a preset range or a custom from / to pair of YYYY-MM-DD days. The presets 7d, 30d and 90d are the last 7, 30 or 90 complete days, ending yesterday, so each comparison with the previous window is whole days against whole days; the dashboard's presets end today, so its numbers can differ slightly. To include today, pass from (and to, which defaults to today). A window that includes today is flagged in the response, because today's numbers are still coming in.

search_logs has no presets. Its from and to take an ISO 8601 date or datetime, a bare to date includes that whole day, and without them it searches the 7 days ending now, today included.

Daily series, including wau and mau, list every day of the window. Windows of two days or less come back hourly instead, listing only hours that have data; wau and mau stay daily. On a daily window, get_trend compares the daily averages of the two windows for dau and engaged, counting days without data as 0 and leaving out days the plan's event limit cut short (listed in incompleteRanges), so the change agrees with the average it reports.

Queries run with time and memory ceilings. A query too large for them fails with a tool error; narrow the window and try again. An argument a tool does not take, such as from sent to get_overview, is rejected with an input error rather than ignored.

Each tool answers with a one-line summary for the agent to quote and the full result as JSON.

Security ​

  • Read-only. The server has no tools that write, delete, or change settings.
  • Scoped to one organization. A connection reads the organization picked when it was allowed. A token reads the organization it was created in. Asking for another organization's extension returns the same "no extension with that id" error as asking for one that does not exist.
  • Your sign-in stays with Moderok. Apps never receive your Google or GitHub account. They get Moderok's own tokens, which work only on https://app.moderok.dev/api/mcp and only for reading analytics.
  • You approve every connection. The sign-in page names the app and where it returns you, every time an app connects.
  • Short-lived. Access tokens last one hour. The refresh token that renews them changes on every use, and if an old one is used again, Moderok ends the connection.
  • Stored as a hash. Moderok stores a SHA-256 hash of every token and sign-in code. The full token exists only in the app, or in the place you pasted an API token. API tokens also keep a short prefix to tell them apart in the list.
  • Revocable. Revoke a connection under Connected apps, or a token under API tokens, in Organization settings → AI tools. It stops working on the next request.
  • Tied to membership. Removing a member, or a member leaving, ends their connections and revokes the API tokens they created. A token whose creator is no longer a member by any other path stops working too, and the token list marks it as inactive.
  • Unrecognized apps need an owner or admin. Their connections last 90 days instead of 365.
  • Rate limited. Each connection and each token can make about 60 requests per minute. Notifications do not count. Past that the server answers 429 with a Retry-After header.
  • Bounded. An organization can have up to 25 active API tokens. Each MCP request carries one JSON-RPC message.
  • Output is untrusted data. Event names, error messages, stacks and property values are written by your extension's installs, and anyone holding the public app key can send events. Treat what the tools return as data, not instructions. Tool summaries never quote it.

Anything a tool returns, including event properties you send with track(), is passed to the agent and to the model provider behind it. If your properties hold anything you would not share with that provider, do not connect an agent to that organization.