Docs/Guides/AVCodex MCP Server

    Authentication

    Last updated · MAR 2026·Read as Markdown

    The AVCodex MCP Server supports two authentication methods: OAuth 2.0 with PKCE (for interactive MCP clients) and API Keys (for automation, CI pipelines, and scripts). This page covers both and how to troubleshoot common issues.

    How it works#

    Note: You don't need to write any code. Your MCP client handles the OAuth flow automatically.

    When you first use an AVCodex MCP tool:

    1. Your MCP client opens a browser window to the AVCodex authorization page.
    2. You log in with your AVCodex account (or you're already logged in).
    3. You approve the connection by clicking "Authorize".
    4. The browser closes and your MCP client is now connected.

    That's it. Your client stores the tokens securely and refreshes them automatically.

    What you'll see#

    #### Authorization screen

    When prompted to authorize, you'll see:

    • AVCodex MCP Server as the application requesting access.
    • Your AVCodex account email to confirm you're logged in.
    • Requested permissions (typically full access to your agents).
    • Authorize and Deny buttons.

    #### After authorization

    Your MCP client will confirm the connection. In Claude Code, you might see:

    code
    Connected to AVCodex MCP Server
Available tools: list_apps, create_app, get_app_analytics...

    Token management#

    AVCodex uses prefixed tokens that your MCP client manages automatically:

    Token type Prefix Lifetime What it does
    Access token avcodex_at_ 1 hour Authenticates each request
    Refresh token avcodex_rt_ 30 days Gets new access tokens when they expire

    Your MCP client:

    • Stores tokens securely in its configuration.
    • Automatically refreshes expired access tokens.
    • Prompts you to re-authorize if the refresh token expires.

    For automation, CI/CD pipelines, and scripts, API keys provide non-interactive auth without the browser flow. Useful when an integration server overnight pulls fresh manufacturer firmware notes into an agent's knowledge base, or when a build script regenerates client-specific support agents.

    Creating an API key#

    1. Go to Settings, Developer, API Keys in your AVCodex dashboard.
    2. Click Create Key and give it a descriptive name.
    3. Optionally select specific permission scopes (or leave full access).
    4. Optionally set an expiration (30 days, 90 days, 1 year, or never).
    5. Copy the key immediately. It is shown only once.

    Key format#

    API keys use the avcodex_sk_ prefix:

    code
    avcodex_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v

    Using API keys#

    Pass the API key as a Bearer token:

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

    Or in direct HTTP requests:

    bash
    curl -X POST https://app.avcodex.com/mcp \
  -H "Authorization: Bearer avcodex_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

    Key security#

    • Keys are hashed in the database. We cannot retrieve your key after creation.
    • Keys can be scoped to specific permissions (read-only, for example).
    • Keys never expire by default. Optionally set 30-day, 90-day, or 1-year expiration.
    • Keys can be revoked instantly from the Developer settings page.
    Warning: Treat API keys like passwords. Never commit them to source control or share them in plaintext. Use environment variables or a secret manager.

    Both OAuth tokens and API keys use the same permission scopes:

    Scope What it allows
    apps:read View your agents
    apps:write Create, update, delete agents
    knowledge:read View knowledge sources
    knowledge:write Add, update, delete knowledge sources
    actions:read View custom actions
    actions:write Manage custom actions
    analytics:read View conversation analytics
    workspace:read View workspace information
    workspace:write Create and update workspaces
    billing:read View subscription and credits
    * All permissions

    Revoking OAuth tokens#

    To disconnect an MCP client from your AVCodex account, revoke your tokens programmatically:

    bash
    # Revoke your refresh token
curl -X POST https://app.avcodex.com/mcp/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "avcodex_rt_your_refresh_token", "token_type_hint": "refresh_token"}'

    For Claude Code, you can also clear stored credentials to force re-authorization:

    bash
    # Remove stored AVCodex OAuth tokens
rm -rf ~/.claude/mcp-auth/avcodex*

    Revoking API keys#

    Go to Settings, Developer, API Keys in your AVCodex dashboard and click Delete next to the key you want to revoke. The key is deactivated immediately.

    After revoking or clearing credentials, your MCP client will prompt you to re-authorize the next time you use an AVCodex tool.

    "Authentication required"#

    What happened: Your token expired and couldn't be refreshed.

    Fix: Your MCP client should automatically prompt you to re-authorize. If not:

    1. Restart your MCP client (for example, restart Claude Code).
    2. Try using an AVCodex tool again to trigger the auth flow.

    "Scope not authorized"#

    What happened: The tool requires a permission that wasn't granted.

    Fix: Re-authorize with broader permissions. Most MCP clients request all scopes automatically, so this is rare.

    Browser doesn't open#

    What happened: The auth flow couldn't open your default browser.

    Fix:

    1. Check if your MCP client logged a URL you can copy and paste.
    2. Ensure a default browser is configured on your system.
    3. Try restarting your MCP client.

    "Invalid token format"#

    What happened: The stored token is corrupted or incomplete.

    Fix:

    1. Clear your MCP client's stored AVCodex credentials.
    2. Re-authorize from scratch.

    For Claude Code, reset credentials:

    bash
    # Remove stored AVCodex OAuth tokens
rm -rf ~/.claude/mcp-auth/avcodex*

    Connection times out#

    What happened: The authorization flow didn't complete in time.

    Fix:

    1. Complete browser authorization within 5 minutes.
    2. Check your internet connection.
    3. Try again. The flow is quick once you know what to expect.

    For those interested in the technical implementation.

    OAuth 2.0 with PKCE#

    The AVCodex MCP Server uses OAuth 2.0 Authorization Code Flow with PKCE:

    • PKCE (Proof Key for Code Exchange) prevents authorization code interception.
    • S256 challenge method required. Plain method is not supported.
    • No client secret required. Safe for desktop applications.
    • Short-lived access tokens. Minimize exposure if compromised.
    • Refresh token rotation. Each refresh immediately revokes the previous access token and refresh token, and issues a new pair. Store the new tokens before discarding the response.

    Token storage#

    Your MCP client stores tokens securely:

    • Claude Code. Encrypted in ~/.claude/ directory.
    • Cursor. Stored in application settings.
    • Custom clients. Should use the OS keychain or encrypted storage.

    For developers building custom MCP clients or debugging issues.

    Endpoints#

    Endpoint Method Purpose
    https://app.avcodex.com/mcp/oauth/authorize GET Start authorization
    https://app.avcodex.com/mcp/oauth/token POST Exchange code for tokens
    https://app.avcodex.com/mcp/oauth/register POST Dynamic client registration
    https://app.avcodex.com/mcp/oauth/revoke POST Revoke tokens
    https://app.avcodex.com/.well-known/oauth-authorization-server GET OAuth discovery

    Authorization request#

    code
    GET https://app.avcodex.com/mcp/oauth/authorize?
  client_id=avcodex_mcp_cli
  &redirect_uri=http://localhost:PORT/callback
  &response_type=code
  &scope=*
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

    Token exchange#

    bash
    POST https://app.avcodex.com/mcp/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "http://localhost:PORT/callback",
  "client_id": "avcodex_mcp_cli",
  "code_verifier": "PKCE_VERIFIER"
}

    Token refresh#

    bash
    POST https://app.avcodex.com/mcp/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "avcodex_rt_xxx",
  "client_id": "avcodex_mcp_cli"
}
    • Rate Limits. Understanding request limits.
    • Tools Reference. All available tools.
    • Common Workflows. Practical examples.

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

    Was this helpful?
    Edit this page →