> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting

> Connect an MCP client to the Artu server — pick your URL, configure your client, and authorize over OAuth

Connect any MCP-compatible client to the Artu MCP server over remote **Streamable HTTP**. There's no API key to paste — you authorize by signing in to Artu in your browser on first connect.

## 1. Pick your connection URL

For most organizations, connecting to the base URL auto-resolves to your organization's scope — you don't need to put a scope in the URL. An optional `live` prefix selects the production environment (the default is `test`). You can target a specific scope by appending its slug (e.g. `mx-av-avi` for `MX:AV:AVI`), which is only needed for multi-scope organizations or to get scope-specific filters.

| Connection URL                       | Environment | Scope                                      |
| ------------------------------------ | ----------- | ------------------------------------------ |
| `https://mcp.artu.ai`                | `test`      | Auto-resolved to your organization's scope |
| `https://mcp.artu.ai/live`           | `live`      | Auto-resolved to your organization's scope |
| `https://mcp.artu.ai/mx-av-avi`      | `test`      | A specific scope (optional override)       |
| `https://mcp.artu.ai/live/mx-av-avi` | `live`      | A specific scope (optional override)       |

Use this URL in the client configuration below. For multi-scope organizations and unscoped connections, see [How scope resolution works](#how-scope-resolution-works).

## 2. Configure your client

There are two ways to connect, depending on what your client supports:

* **Native remote MCP** — the client connects to the Streamable HTTP URL directly and runs the OAuth flow for you (opens a browser, stores the token). Claude Code, Claude Desktop, Cursor, and VS Code work this way.
* **The `mcp-remote` bridge** — clients that only speak stdio, or don't yet implement the OAuth handshake (Codex, Cline, Windsurf, and others), run [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local proxy. It performs the OAuth flow, caches the token, and forwards to the remote server. Requires [Node.js](https://nodejs.org/).

The snippets below use the default URL `https://mcp.artu.ai` (auto-scoped, `test`). For production, use `https://mcp.artu.ai/live`; to pin a specific scope, append its slug as shown in the table above.

### Claude Code

```bash theme={null}
claude mcp add --transport http artu https://mcp.artu.ai
# live environment:
claude mcp add --transport http artu https://mcp.artu.ai/live
```

Claude Code opens the OAuth flow in your browser on first use.

### Claude Desktop

Add a remote MCP server in **Settings → Connectors** (or your installed-connectors UI) pointing at the Streamable HTTP URL, `https://mcp.artu.ai`. Authenticate when prompted.

### Cursor

Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). Cursor connects to the URL directly and runs the OAuth flow on first use:

```json theme={null}
{
  "mcpServers": {
    "artu": {
      "url": "https://mcp.artu.ai"
    }
  }
}
```

### VS Code (GitHub Copilot)

Add the server to `.vscode/mcp.json` in your workspace (note VS Code uses the `servers` key and an explicit `type`):

```json theme={null}
{
  "servers": {
    "artu": {
      "type": "http",
      "url": "https://mcp.artu.ai"
    }
  }
}
```

Start the server from the `mcp.json` editor (or **MCP: List Servers**) and complete the OAuth flow when prompted.

### Codex CLI

Codex's native HTTP MCP support expects a static token, so use the `mcp-remote` bridge for the OAuth flow. Add to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.artu]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.artu.ai"]
```

On first run, `mcp-remote` opens your browser to authenticate, then caches the token under `~/.mcp-auth`.

### Other clients (Cline, Windsurf, and any stdio-only client)

Any client that can launch a stdio MCP server can reach Artu through the same `mcp-remote` bridge. Configure a server whose command is:

```bash theme={null}
npx -y mcp-remote https://mcp.artu.ai
```

For JSON-configured clients (most use an `mcpServers` map), that is:

```json theme={null}
{
  "mcpServers": {
    "artu": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.artu.ai"]
    }
  }
}
```

### MCP Inspector

The [Inspector](https://github.com/modelcontextprotocol/inspector) is the quickest way to explore tools and capture a real token:

```bash theme={null}
npx @modelcontextprotocol/inspector
```

Enter the Streamable HTTP URL, complete the OAuth flow, then browse `tools/list` and call tools interactively.

## How the connection works

### Transport and auth

The Artu MCP server speaks **MCP Streamable HTTP** and authenticates with **OAuth 2.1**. Compatible clients run the OAuth flow automatically on first connect and store the token for you — there's no API key to paste; you authorize by signing in to Artu in your browser.

### How scope resolution works

* **Single-scope organizations** can connect to the base URL — it auto-resolves to your scope. This is the default shown above.
* **Multi-scope organizations** that connect to the base URL get an **unscoped, read-only** connection across every scope you're entitled to. List tools accept an optional `scope` argument to narrow results, and `get_client_checklist` requires one. To get the flattened scope-specific filters (e.g. `rfc`, `curp`), connect to a scope-specific URL instead.

Call `whoami` after connecting to confirm the resolved organization, environment, scope (`null` when unscoped), and available scopes.