Getting Started

Connecting Agents

How to set up agent harnesses and agent runtimes

Summary

A quick-start for connecting the most common agents. Use the View as Markdown at the top 👆 and give it to your agents.

👉 Before connecting a client, create an account first

After connecting, the easiest way to verify the connection is to run a simple prompt:

Terminal

# The quip tool will return a small joke
> claude "Get a quip from zeeq"
>
> codex "Get a quip from zeeq"

Selecting auth mechanism

Zeeq supports three authentication mechanisms for connecting agents:

Mechanism	Best for...
Dynamic client registration (DCR)	Most use cases should simply use DCR to authenticate the MCP server after creating an account
API Token	Least friction long term since it never requires re-authentication while the token is valid and not revoked. In some cases, this is preferred; for example, when a codebase needs to support running in Codespaces as well since the token can be configured as a user level secret.
Client ID + Client Secret	Supported inconsistently by harnesses; use as an alternative to API token (but user may be better served with API token)

The examples here use ZEEQ_ACCESS_TOKEN as the environment variable name for the API token. You can use any name you like; use consistently in your config.

Claude Code CLI

In both cases, you will need to then use /mcp slash command after starting a new session to authenticate.

Setup via command line

Terminal

# Per project installation recommended
claude mcp add --scope project --transport http zeeq https://app.zeeq.ai/mcp

Alternate: setup in `.mcp.json`

// Per project installation in the .mcp.json file:
{
  "mcpServers": {
    "zeeq": {
      "type": "http",
      "url": "https://app.zeeq.ai/mcp",
      "timeout": 120000
    },
  }
}

// Per project installation in the .mcp.json file:
{
  "mcpServers": {
    "zeeq": {
      "type": "http",
      "url": "https://app.zeeq.ai/mcp",
      "timeout": 120000,
      "headers": {
        "Authorization": "Bearer ${ZEEQ_ACCESS_TOKEN}"
      }
    },
  }
}

The long timeout supports the MCP call to run the remote code review

Claude Code Desktop

Access Settings
Scroll down and click Connectors on the left
Click the Add button on the top right
Click Add custom connector
Enter Zeeq for the Name
Enter https://app.zeeq.ai/mcp for the Remote MCP server URL

Codex CLI

Set via command line

Terminal

# Global install; no project local option via command line
codex mcp add zeeq --url https://app.zeeq.ai/mcp

Then:

Terminal

codex mcp login zeeq

Alternate: set up in `.codex/config.toml`

# Per project installation in the .codex/config.toml file:
[mcp_servers.zeeq]
enabled = true
url = "https://app.zeeq.ai/mcp"

# Per project installation in the .codex/config.toml file:
[mcp_servers.zeeq]
enabled = true
url = "https://app.zeeq.ai/mcp"
bearer_token_env_var = "ZEEQ_ACCESS_TOKEN"

Then:

Terminal

codex mcp login zeeq

Codex Desktop

Click on Settings
Find Plugins on the left
Click the MCPs pill at the top
Click Add server
Select Streamable HTTP for Type
Enter Zeeq for Name
Enter https://app.zeeq.ai/mcp for URL

Cursor

Cursor desktop mode

On the left click Tools & MCPs
Click the Open Customize button at the top
Click the MCPs pill
Click +New
A right panel opens to edit mcp.json

{
  "mcpServers": {
    "zeeq": {
      "url": "https://app.zeeq.ai/mcp",
      "auth": {
        "scopes": ["mcp:tools"]
      }
    }
  }
}

{
  "mcpServers": {
    "zeeq": {
      "url": "https://app.zeeq.ai/mcp",
      "auth": {
        "scopes": ["mcp:tools"]
      },
      "headers": {
        "Authorization": "Bearer ${env:ZEEQ_ACCESS_TOKEN}"
      }
    }
  }
}

Finish the authentication flow through the UI

Cursor IDE editor mode

Add or edit .cursor/mcp.json (see snippet above)
Navigate to Cursor settings
Click Tools & MCPs
Find Zeeq and click Authenticate

GitHub Copilot Cloud Agents

This is for GitHub Copilot Cloud Agents only; not the local desktop VS Code configuration and not Codespaces. These launch in GitHub Actions and have separate configuration

Create an access/API token in Zeeq first via: https://app.zeeq.ai/web/settings/credentials

In the GitHub repository, navigate to Settings
Expand Secrets and variables
Click Agents
Under Repository secrets, add a new secret with the token created from ZeeqCOPILOT_MCP_CLOUD_AGENT_BIBLIO_ACCESS_TOKEN
Expand Copilot on the left
Click Cloud agent
Scroll down to MCP configuration

{
  "mcpServers": {
    "zeeq": {
      "type": "http",
      "url": "https://app.zeeq.ai/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_CLOUD_AGENT_ZEEQ_ACCESS_TOKEN"
      },
      "tools": ["*"]
    }
  }
}

Important: the secret MUST be prefixed with $COPILOT_MCP_

GitHub Codespaces

Create an access/API token in Zeeq first via: https://app.zeeq.ai/web/settings/credentials

GitHub Codespaces can be set up to use long-lived API tokens to make authentication more straightforward.

Navigate to your user Settings (https://github.com/settings/profile)
Click Codespaces on the left (https://github.com/settings/codespaces)
Add a New secret and name it ZEEQ_ACCESS_TOKEN (arbitrary)
In the Codespace setup (depending on your harness), use header authentication instead

# Codex example (recommend pre-building into container) .codex/config.toml file:
[mcp_servers.zeeq]
enabled = true
url = "https://app.zeeq.ai/mcp"
bearer_token_env_var = "ZEEQ_ACCESS_TOKEN"

OpenCode

In your .config/opencode.json or ./opencode.json local to the project:

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "mcp_timeout": 300000
  },
  "mcp": {
    "zeeq": {
      "type": "remote",
      "enabled": true,
      "url": "https://app.zeeq.ai/mcp"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "mcp_timeout": 300000
  },
  "mcp": {
    "zeeq": {
      "type": "remote",
      "enabled": true,
      "url": "https://app.zeeq.ai/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:ZEEQ_ACCESS_TOKEN}",
      },
    }
  }
}

Then:

Terminal

opencode mcp auth zeeq

VS Code Copilot

Setup via `code`

Terminal

code --add-mcp "{\"name\":\"zeeq\",\"type\": \"http\",\"url\": \"https://app.zeeq.ai/mcp\"}"

Setup via `.vscode/mcp.json`

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

{
  "servers": {
    "zeeq": {
      "type": "http",
      "url": "https://app.zeeq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:zeeq_server_access_token}"
      }
    }
  },
  "inputs": [
    {
      "id": "zeeq_server_access_token",
      "type": "promptString",
      "description": "Enter your access token from the Zeeq UI",
      "password": true
    }
  ]
}

You can click on the "Start" inlay in the mcp.json file to initiate the auth.

Connecting telemetry

See Session Telemetry for instructions on connecting telemetry from your agent harness.

Edit this pageorReport an issue

Org Onboarding

How to get your organization set up, connected to GitHub, and ready for MCP clients

Harness Tuning

How to tune your harness or agents to get the most out of Zeeq