# Xquik MCP server setup

Add the remote URL & complete OAuth 2.1 in the browser.
For clients without OAuth, use [API key fallback](#api-key-fallback).

Xquik receives authenticated tool requests through its remote MCP service.
Review the OAuth consent screen and tool list before connecting.
Grant only the access needed for the task.
An API key grants its documented access until revoked.

| Setting | Value |
|---------|-------|
| Protocol | Streamable HTTP |
| Endpoint | `https://xquik.com/mcp` |
| Authentication | OAuth 2.1 discovery, with API key fallback |
| Skill bundle version | `2.7.1` |

Current clients negotiate MCP `2026-07-28` through `server/discover`.
Use a current MCP SDK. It adds request `_meta` and protocol headers.
Modern calls need no `initialize` request or session ID.
Discovery and tool catalogs include private 5-minute cache hints.
Reuse cached metadata only with the same authorization context.
Stateless 2025-era clients remain compatible at the same endpoint.

Xquik publishes these discovery documents.

- The protected resource metadata is at `https://xquik.com/.well-known/oauth-protected-resource/mcp`
- The authorization server metadata is at `https://xquik.com/.well-known/oauth-authorization-server`
- The MCP registry card is at `https://xquik.com/.well-known/mcp/server-card.json`
- The authentication guide is at `https://xquik.com/auth.md`

Xquik supports Client ID Metadata Documents and Dynamic Client Registration.
Let each client use its documented registration flow. Both
use Authorization Code with S256 PKCE and the `mcp:tools` scope.

Use the [canonical client compatibility matrix](https://docs.xquik.com/mcp/overview#client-compatibility)
for current per-client support. Cline and Qwen Code support OAuth.
Affected Goose releases need an environment-backed API key. Roo Code's archived final
release is API-key-only. Pi has no native MCP client.

> Start OAuth from the MCP client. Do not open Xquik login routes
> directly. Do not proxy Xquik credentials through local bridge packages or
> command-line adapters.

## Claude

### Claude.ai

1. Open [Claude Connectors](https://claude.ai/settings/connectors) or **Customize > Connectors**.
2. Select **+**, then **Add custom connector**.
3. Enter `https://xquik.com/mcp`.
4. Select **Add**.
5. In a chat, select **+ > Connectors**, enable Xquik, then select **Connect** and approve access.

Leave advanced client ID and client secret fields empty. Free accounts can add
1 custom connector. On Team and Enterprise plans, an Owner or Primary Owner
must first add the Web connector under **Organization settings > Connectors >
Add > Custom**. The feature is currently beta.

### Claude Desktop

Claude Desktop uses the same remote custom connectors. Open **Customize >
Connectors**, add `https://xquik.com/mcp`, then complete browser authorization.

### Claude Code

```bash
claude mcp add --transport http xquik https://xquik.com/mcp
```

Run `/mcp`, select `xquik`, then authenticate.

## OpenAI

### ChatGPT

1. In ChatGPT on the web, open **Settings > Apps > Advanced settings** and enable **Developer mode**.
2. Open **Settings > Apps > Create**. Workspace administrators may instead use **Workspace settings > Apps > Create**.
3. Enter `https://xquik.com/mcp`, choose OAuth, then select **Scan tools**.
4. Complete Xquik authorization and select **Create**.

Check your plan & workspace controls before setup.

### Codex CLI

Use a current Codex CLI release. Run these commands.

```bash
codex mcp add xquik --url https://xquik.com/mcp
codex mcp login xquik
codex mcp list
```

If an older release reports
`Authorization server response missing required issuer: expected https://xquik.com`,
update Codex. If an update is unavailable, use the API-key fallback below. Follow the
[Xquik troubleshooting guide](https://docs.xquik.com/guides/troubleshooting#codex-oauth-issuer-validation-error).

### Codex Desktop

Open **Settings > MCP servers**. Add `https://xquik.com/mcp` as Streamable HTTP,
select **Authenticate**, then restart. Use the shared `config.toml` fallback
below only when OAuth shows the issuer error.

### API-key fallback for older Codex releases

In Codex Settings, follow [API key fallback](#api-key-fallback) & add this block.

```toml
[mcp_servers.xquik]
url = "https://xquik.com/mcp"
bearer_token_env_var = "XQUIK_API_KEY"
```

Restart Codex, then run `codex mcp list`. Do not run `codex mcp login xquik`
while using the API-key configuration.

After updating Codex, remove `bearer_token_env_var`. Leave only
the MCP URL, then run `codex mcp login xquik`.

### OpenAI Agents SDK

For runtimes without OAuth, follow [API key fallback](#api-key-fallback).
This function returns only the MCP setting & makes no request.
Integration stays outside this Skill.

```python
from agents.mcp import MCPServerStreamableHttp


def build_xquik_server(api_key: str) -> MCPServerStreamableHttp:
    return MCPServerStreamableHttp(
        name="Xquik",
        params={
            "url": "https://xquik.com/mcp",
            "headers": {"Authorization": f"Bearer {api_key}"},
        },
    )
```

## Editor and terminal clients

### Cursor

Add this to `~/.cursor/mcp.json` or `.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "xquik": {
      "url": "https://xquik.com/mcp"
    }
  }
}
```

Cursor starts OAuth after the server returns `401`. You can also run
`cursor-agent mcp login xquik`.

### VS Code

Add this to `.vscode/mcp.json` or run the `MCP: Open User Configuration` command.

```json
{
  "servers": {
    "xquik": {
      "type": "http",
      "url": "https://xquik.com/mcp"
    }
  }
}
```

Start the server from the MCP view and follow the OAuth prompt.

### Windsurf

Add this to `~/.codeium/windsurf/mcp_config.json`.

```json
{
  "mcpServers": {
    "xquik": {
      "serverUrl": "https://xquik.com/mcp"
    }
  }
}
```

Enable the server in **Windsurf Settings > Cascade > MCP Servers**, then
complete OAuth. Enterprise users must enable MCP manually. Team policies may
disable MCP or restrict servers to an allowlist.

### OpenCode

Add this to `opencode.json`.

```json
{
  "mcp": {
    "xquik": {
      "type": "remote",
      "url": "https://xquik.com/mcp"
    }
  }
}
```

Then run these commands.

```bash
opencode mcp auth xquik
opencode mcp list
```

### Gemini CLI

Add the remote server.

```bash
gemini mcp add --transport http xquik https://xquik.com/mcp
```

Run `/mcp auth xquik` to complete OAuth.

### GitHub Copilot CLI

```bash
copilot mcp add --transport http xquik https://xquik.com/mcp
```

If your installed CLI does not recognize those flags, start `copilot`, run
`/mcp add`, choose HTTP, name the server `xquik`, enter the endpoint above, and
save. This interactive path works across Copilot CLI command variants.

In an interactive Copilot CLI session, run `/mcp auth xquik`. Enterprise policy
may block servers that are not on the organization allowlist.

## API key fallback

Use fallback only when the client cannot complete OAuth.
Use its documented secure secret-input or environment-variable mechanism.
Load `XQUIK_API_KEY` from a password manager or operating-system secret store.
Keep keys out of shell commands, history, configuration files, tool code, & commits.
Client schemas & environment syntax differ. Never copy headers between clients.
ChatGPT custom apps require OAuth. Older Codex releases use `bearer_token_env_var` above.

Each key exposes its allowed catalog. Active guest `paid_reads` keys expose
eligible read routes only.

## After setup

[Use docs, search, & execute safely](../SKILL.md#tools).
Binary downloads & uncataloged account changes use REST or dashboard flows.