# Setup and Installation

Connect the AVCodex MCP Server to Claude Code, Cursor, or any MCP client.

---

This guide walks through connecting the AVCodex MCP Server to your preferred AI coding assistant. If you write Crestron SIMPL# Pro in VS Code, work in Cursor on Q-SYS Lua modules, or just live in Claude Code, you can drive AVCodex from your editor.

## Prerequisites

- **Builder plan or higher.** MCP access requires a paid subscription ([upgrade here](https://app.avcodex.com/plans)).
- **AVCodex account.** Sign up at [app.avcodex.com](https://app.avcodex.com) if you haven't already.

## Claude Code

Claude Code has built-in MCP support. Add AVCodex to your configuration file.

### Step 1: Open the configuration

The configuration file is located at `~/.claude.json` (your home directory).

```bash
# macOS/Linux
nano ~/.claude.json

# Or open with your preferred editor
code ~/.claude.json
```

### Step 2: Add the server

Add the AVCodex server to the `mcpServers` section:

```json
{
  "mcpServers": {
    "avcodex": {
      "url": "https://app.avcodex.com/mcp",
      "transport": "streamable-http"
    }
  }
}
```

If you already have other MCP servers configured:

```json
{
  "mcpServers": {
    "existing-server": {
      "...": "..."
    },
    "avcodex": {
      "url": "https://app.avcodex.com/mcp",
      "transport": "streamable-http"
    }
  }
}
```

### Step 3: Restart Claude Code

Close and reopen Claude Code for the changes to take effect.

### Step 4: Authenticate

The first time you use an AVCodex tool, Claude Code will:
1. Open your browser to the AVCodex authorization page.
2. Ask you to log in (if you aren't already).
3. Show the permissions being requested.
4. Return an authorization code to Claude Code.

After authorization, your tokens are stored securely and refreshed automatically.

### Step 5: Verify the connection

Ask Claude to list your agents:

```
List all my AVCodex agents
```

You should see a list of your agents. If you see an error, check the Troubleshooting section below.

---

## Cursor

Cursor supports MCP through its settings panel.

### Step 1: Open settings

1. Open Cursor.
2. Go to **Settings** (Cmd/Ctrl + ,).
3. Search for "MCP" or navigate to the MCP section.

### Step 2: Add the server

Add a new MCP server with these settings:

| Field | Value |
|-------|-------|
| Name | `avcodex` |
| URL | `https://app.avcodex.com/mcp` |
| Transport | `streamable-http` |

Or add directly to your Cursor settings JSON:

```json
{
  "mcp": {
    "servers": {
      "avcodex": {
        "url": "https://app.avcodex.com/mcp",
        "transport": "streamable-http"
      }
    }
  }
}
```

### Step 3: Authenticate

When you first use AVCodex tools, Cursor will prompt you to authorize via your browser.

---

## Generic MCP client

For any MCP-compatible client, use these connection details.

### Server configuration

```json
{
  "name": "avcodex",
  "url": "https://app.avcodex.com/mcp",
  "transport": "streamable-http"
}
```

### OAuth discovery

The server supports OAuth discovery via:

```
GET https://app.avcodex.com/.well-known/oauth-authorization-server
```

Response:
```json
{
  "issuer": "https://app.avcodex.com",
  "authorization_endpoint": "https://app.avcodex.com/mcp/oauth/authorize",
  "token_endpoint": "https://app.avcodex.com/mcp/oauth/token",
  "registration_endpoint": "https://app.avcodex.com/mcp/oauth/register",
  "revocation_endpoint": "https://app.avcodex.com/mcp/oauth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"]
}
```

### Manual OAuth flow

If your client doesn't support automatic OAuth, implement the flow manually:

1. **Generate a PKCE challenge** (S256 method required).
2. **Redirect to authorize**:
   ```
   https://app.avcodex.com/mcp/oauth/authorize?
     client_id=your_client_id
     &redirect_uri=your_callback_url
     &response_type=code
     &scope=*
     &code_challenge=YOUR_CHALLENGE
     &code_challenge_method=S256
     &state=random_state
   ```
3. **Exchange the code for tokens**:
   ```bash
   POST https://app.avcodex.com/mcp/oauth/token
   Content-Type: application/json

   {
     "grant_type": "authorization_code",
     "code": "AUTH_CODE",
     "redirect_uri": "your_callback_url",
     "client_id": "your_client_id",
     "code_verifier": "YOUR_VERIFIER"
   }
   ```
4. **Use the access token** in requests:
   ```
   Authorization: Bearer avcodex_at_xxxxx
   ```

See the Authentication Guide for full details.

---

## Alternative: API keys

For automation and scripts, you can use API keys instead of OAuth.

1. Go to **Settings, Developer, API Keys** in your AVCodex dashboard.
2. Click **Create Key** and give it a name.
3. Copy the key (shown only once).
4. Use it in your requests:

```json
{
  "mcpServers": {
    "avcodex": {
      "url": "https://app.avcodex.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer avcodex_sk_xxxxx"
      }
    }
  }
}
```

See the Authentication Guide for more on API key management.

---

## Endpoints reference

| Endpoint | Purpose |
|----------|---------|
| `https://app.avcodex.com/mcp` | Main MCP endpoint (POST JSON-RPC) |
| `https://app.avcodex.com/health` | Health check |
| `https://app.avcodex.com/.well-known/oauth-authorization-server` | OAuth discovery |
| `https://app.avcodex.com/mcp/oauth/authorize` | OAuth authorization |
| `https://app.avcodex.com/mcp/oauth/token` | Token exchange |
| `https://app.avcodex.com/mcp/oauth/register` | Dynamic client registration |
| `https://app.avcodex.com/mcp/oauth/revoke` | Token revocation |

---

## Troubleshooting

### "MCP server not found"

**Cause:** Configuration file not loaded or syntax error.

**Fix:**
1. Verify JSON syntax (use a validator).
2. Check the config file path is correct.
3. Restart your MCP client.

### "Authentication required"

**Cause:** No valid token, or token expired.

**Fix:**
1. Trigger a tool call to start the OAuth flow.
2. Complete authorization in the browser.
3. If the flow fails, clear cached tokens and retry.

### "Connection refused"

**Cause:** Network issue or URL typo.

**Fix:**
1. Verify URL: `https://app.avcodex.com/mcp`.
2. Check internet connection.
3. Try the health endpoint: `curl https://app.avcodex.com/health`.

### "Invalid scope"

**Cause:** Requesting unauthorized permissions.

**Fix:**
1. Use `scope=*` for all permissions, or
2. Request only the scopes you need (e.g., `apps:read apps:write`).

### "Rate limit exceeded"

**Cause:** Too many requests for your subscription tier.

**Fix:**
1. Wait for the reset time (check `Retry-After` header).
2. Consider upgrading your plan for higher limits.
3. See the Rate Limits Guide for best practices.

### Clearing cached tokens

If you need to re-authenticate:

**Claude Code:**
```bash
# Find and remove AVCodex tokens
rm -rf ~/.claude/mcp-tokens/avcodex*
```

**Cursor:**
- Go to Settings, MCP, AVCodex, Remove/Reconnect.

---

## Testing your connection

After setup, verify with these commands.

### Basic test

```
"List my AVCodex agents"
```

Expected: a list of your agents with IDs and names.

### Permission test

```
"Create a test agent called MCP-Test with a simple greeting prompt"
```

Expected: agent created successfully with an ID returned.

### Cleanup

```
"Delete the agent named MCP-Test"
```

Expected: deletion confirmation.

> **Success:** If all three tests pass, you're ready to use the AVCodex MCP Server.

## Next steps

- Authentication. Deep dive into OAuth and API keys.
- Tools reference. Every available tool.
- Common workflows. Step-by-step examples.

*AVCodex · Your AV expertise. Amplified by AI.*