---
title: "Set up Optimi MCP"
description: "Connect your coding assistant to Optimi MCP with OpenCode, Claude Code, Codex, or another compatible client. Sign in and query analytics and job status."
canonical_url: https://optimi.com/en/docs/mcp
md_url: https://optimi.com/en/docs/mcp.md
last_updated: 2018-10-20
---

# Set up Optimi MCP

Optimi's Model Context Protocol (MCP) endpoint lets your coding assistant
inspect analytics and job status using your Optimi account. Connect with
OpenCode, Claude Code, Codex, or another MCP client that supports the transport
and authentication described below.

The endpoint is hosted at `https://dash.optimi.com/mcp`. You connect to this
remote service; there is no local Optimi MCP server to install.

## Before you start

- Install your preferred MCP-compatible coding assistant.
- Have an Optimi account with access to at least one tenant.
- For another deployment, use its origin followed by `/mcp` instead of the
  hosted URL below. That deployment must have MCP login configured.

## 1. Add the MCP server

Use these connection settings in your assistant:

| Setting | Value |
| --- | --- |
| Server name | `optimi` |
| URL | `https://dash.optimi.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth with protected-resource discovery and dynamic client registration |

Leave the client ID, client secret, tenant header, and OAuth scope unset. The
client discovers the authentication settings, registers itself, and requests
the scopes advertised by the endpoint. It must request a token for the MCP URL
using the OAuth `resource` parameter.

Choose the instructions for your client below.

### OpenCode

Add the following to `opencode.json` in your project root, or to
`~/.config/opencode/opencode.json` to use it across projects. If you already
have a configuration file, merge the `optimi` entry into its `mcp` object.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "optimi": {
      "type": "remote",
      "url": "https://dash.optimi.com/mcp"
    }
  }
}
```

Restart OpenCode after saving the configuration. See the
[OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/) for client
configuration options.

### Claude Code

From your project directory, add the remote HTTP server:

```sh
claude mcp add --transport http optimi https://dash.optimi.com/mcp
```

By default, the entry is private to you in the current project. Add
`--scope user` to make it available across projects. See the
[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for
configuration scopes and options.

### Codex

Add the remote server with the Codex CLI:

```sh
codex mcp add optimi --url https://dash.optimi.com/mcp
```

Alternatively, add this entry to `~/.codex/config.toml`:

```toml
[mcp_servers.optimi]
url = "https://dash.optimi.com/mcp"
```

The Codex CLI and IDE extension share this configuration. See the
[Codex MCP documentation](https://developers.openai.com/codex/extend/mcp) for
client configuration options.

### Other MCP clients

In your client's MCP settings, add a remote server named `optimi` with the URL
above, choose Streamable HTTP, and enable automatic OAuth authentication. The
client needs protected-resource discovery, dynamic client registration, and
OAuth resource indicators. A client that only supports local stdio servers or
static API keys cannot complete this login flow.

## 2. Sign in

Start authentication using your client's command or MCP settings:

| Client | Sign in | Check connection status |
| --- | --- | --- |
| OpenCode | Run `opencode mcp auth optimi` from your project directory. | `opencode mcp list` |
| Claude Code | Start `claude`, open `/mcp`, select `optimi`, and choose **Authenticate**. | `/mcp` or `claude mcp list` |
| Codex | Run `codex mcp login optimi`. | `codex mcp list` or `/mcp` in the Codex TUI |
| Other clients | Use the server's **Connect**, **Sign in**, or **Authenticate** action. | Check the client's MCP server status. |

Complete the sign-in flow in your browser using your Optimi account. Your
client stores the resulting credentials for subsequent requests.

MCP uses a token whose audience is the exact MCP URL. A dashboard or CLI login
token cannot be used in its place.

## 3. Choose a tenant and try a query

Ask your assistant:

> Use Optimi MCP to list the tenants I can access, then show the available
> analytics datasets for the tenant I choose.

The assistant should call `list_tenants` first. If you have access to more
than one tenant, it asks which to use and passes the returned ID as `tenantId`
on subsequent tool calls. With a single tenant, `tenantId` can be omitted.

Once the tenant is selected, try:

> Use Optimi MCP to summarize my traffic over the last 24 hours and show the
> status of my recent export jobs.

The assistant uses `analytics_catalog` to discover datasets and metrics before
calling `query_analytics`. Tool availability follows your existing permissions
and the selected tenant's entitlements.

## Available tools

| Tool | What it does |
| --- | --- |
| `list_tenants` | Lists the tenants your account can access. |
| `get_context` | Shows the selected tenant and your effective scopes. |
| `analytics_catalog` | Lists available analytics datasets, metrics, dimensions, and filters. |
| `query_analytics` | Runs a bounded analytics query. |
| `list_jobs` | Lists recent jobs, including exports. |
| `get_job` | Reads the status of a specific job. |

All tools are read-only. They cannot change CDN configuration, purge content,
modify billing, or change memberships. Analytics queries default to 100 rows
and support a maximum of 500. Job responses omit job payloads.

## Troubleshooting

For connection or sign-in problems, check your client's MCP status first.
OpenCode also provides `opencode mcp debug optimi` for connection and OAuth
discovery diagnostics. In Claude Code, use `/mcp` or `claude mcp get optimi`;
in Codex, use `/mcp` or `codex mcp list`.

| Symptom | What to check |
| --- | --- |
| `optimi` is missing from the server list | Check the configuration location or scope and restart your client. Run project-scoped commands from that project. |
| Sign-in cannot complete | Confirm the URL ends in `/mcp`. For another deployment, ask its operator to verify the MCP resource and dynamic client registration in Auth0. |
| HTTP 401 | Sign in again using your client's authentication action above. If the `WWW-Authenticate` response header lacks `resource_metadata`, the request did not reach the Optimi MCP endpoint; check the URL and routing. |
| HTTP 403 after sign-in | The endpoint rejected the signed-in identity. Ask your Optimi administrator to check your account access. |
| `insufficient_permissions` | You are signed in, but your permissions do not allow that tool. Ask your tenant administrator to check your role. |
| `entitlement_required` | The selected tenant does not have the entitlement required by that tool. |

## Disconnect

Use your client's MCP settings to sign out or clear the server's stored
authentication. In OpenCode, run `opencode mcp logout optimi`. In Claude Code,
open `/mcp`, select `optimi`, and choose **Clear authentication**.

To stop loading the integration, remove or disable the `optimi` server in your
client. In OpenCode, set `"enabled": false` in the JSON server entry; in
Codex, set `enabled = false` in the TOML server entry. In Claude Code,
use `/mcp` to disable the server or run `claude mcp remove optimi` to remove it.