# Set up Obelism numbers for an AI agent

These are the official instructions from Obelism to connect an AI coding agent to numbers, the web analytics of every site on Obelism at https://numbers.obelism.studio. They are published at `https://numbers.obelism.studio/agent-setup.md`, so you can check them against that URL at any time.

Do the steps yourself by running the commands and editing the config files directly. Only hand a step to the user where it says so: signing in happens in their browser.

1. Connect the numbers MCP server
2. Point the agent at the numbers docs
3. Tell the user what was done

---

## 1. Connect the numbers MCP server

The server is `https://numbers.obelism.studio/mcp` (Streamable HTTP). Its tools are the numbers agent API, and they only read: list organizations and spaces, get a space's report (visitors, pages, sources, campaigns, countries, devices, clicked elements) and list the events it received.

It signs the user in with OAuth. There is no API key to copy: on first use the client opens numbers in the browser, the user signs in with their Obelism account and allows the connection. Someone without an account can create one on that same sign-in page.

Use the section for your agent. Register the server globally (for the user), not only for the current project, unless the user asks otherwise. If an entry called `numbers` already exists, update it instead of adding a second one, and keep every other setting in the file as it was.

### Claude Code

```
claude mcp add --transport http --scope user numbers https://numbers.obelism.studio/mcp
```

Then tell the user to run `/mcp` inside Claude Code, pick `numbers` and choose Authenticate.

### Codex

```
codex mcp add numbers --url https://numbers.obelism.studio/mcp
codex mcp login numbers
```

### OpenCode: `~/.config/opencode/opencode.jsonc`

Add under `"mcp"`:

```json
"numbers": { "type": "remote", "url": "https://numbers.obelism.studio/mcp", "enabled": true, "oauth": {} }
```

Then run:

```
opencode mcp auth numbers
```

### Cursor: `~/.cursor/mcp.json`

Add under `"mcpServers"`:

```json
"numbers": { "url": "https://numbers.obelism.studio/mcp" }
```

The sign-in starts on the first numbers tool call, or from Cursor's MCP settings.

### GitHub Copilot in VS Code: `.vscode/mcp.json`, or the user `mcp.json` from "MCP: Open User Configuration"

Add under `"servers"` (VS Code uses `servers`, not `mcpServers`):

```json
"numbers": { "type": "http", "url": "https://numbers.obelism.studio/mcp" }
```

### Windsurf / Devin Desktop: `~/.codeium/windsurf/mcp_config.json`

Add under `"mcpServers"` (note `serverUrl`, not `url`):

```json
"numbers": { "serverUrl": "https://numbers.obelism.studio/mcp" }
```

### Claude (web and desktop) and other apps with connectors

You can't add these yourself. Tell the user to add a custom connector with the URL `https://numbers.obelism.studio/mcp`.

### Any other MCP client

Register a remote server named `numbers` at `https://numbers.obelism.studio/mcp` with OAuth. The client finds everything else on its own: the server's `401` points to `/.well-known/oauth-protected-resource/mcp`, and clients register with a Client ID Metadata Document or Dynamic Client Registration.

---

## 2. Point the agent at the numbers docs

numbers has no skills package. The docs are written for agents instead. Ask the user whether to add this line to the user-level instructions file for your agent, such as `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex, or `~/.config/opencode/AGENTS.md` for OpenCode. Skip this step if they say no.

```
For a site's visitors, pages, sources and events with Obelism numbers, read https://numbers.obelism.studio/llms.txt first, and use the numbers MCP tools to read reports.
```

---

## 3. Tell the user what was done

```
┌─ Obelism numbers agent setup ────────────────────────┐
│  ✓ MCP server   <config file or command used>        │
│  ✓ Docs         <instructions file, or skipped>      │
│                                                      │
│  Restart your agent, then sign in to numbers when    │
│  it opens the browser.                               │
└──────────────────────────────────────────────────────┘
```

If the user wants to add numbers to the project they are working in, that is a separate job: follow https://numbers.obelism.studio/docs/getting-started to add the script or the SDK.

---

## Resources

- numbers MCP server and agent API: `https://numbers.obelism.studio/docs/agents`
- Docs index for agents: `https://numbers.obelism.studio/llms.txt`
- OpenAPI spec: `https://numbers.obelism.studio/openapi.json`
- Claude Code MCP: `https://docs.anthropic.com/en/docs/claude-code/mcp`
- Codex MCP: `https://developers.openai.com/codex/mcp`
- OpenCode MCP: `https://opencode.ai/docs/mcp-servers/`
- Cursor MCP: `https://cursor.com/docs/mcp`
- VS Code MCP: `https://code.visualstudio.com/docs/copilot/customization/mcp-servers`
- Questions: hello@obelism.studio