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.

• Builder plan or higher. MCP access requires a paid subscription (upgrade here).
• AVCodex account. Sign up at app.avcodex.com if you haven't already.

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).

# 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:

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

If you already have other MCP servers configured:

{
  "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 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:

Or add directly to your Cursor settings 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.

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

Server configuration#

{
  "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:

{
  "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 ``

1. 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" } ```

1. Use the access token in requests:

`` Authorization: Bearer avcodex_at_xxxxx ``

See the Authentication Guide for full details.

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:

{
  "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.

"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:

# Find and remove AVCodex tokens
rm -rf ~/.claude/mcp-tokens/avcodex*

Cursor:

• Go to Settings, MCP, AVCodex, Remove/Reconnect.

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.

• 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.*