Authentication

Overview

Hopkin supports two authentication methods. Both produce the same internal auth context — your tools work identically regardless of which method you choose.

API Keys (Recommended)

API keys are the simplest way to authenticate. They work with all MCP clients and require no browser interaction.

Getting an API Key

• Go to app.hopkin.ai/api-keys
• Click Generate New Key
• Copy the key (starts with hpk_live_...)

Using Your API Key

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer hpk_live_your_key_here

In Claude Code:

claude mcp add --transport http -H "Authorization:Bearer hpk_live_..." hopkin-meta-ads https://meta.mcp.hopkin.ai

In a config file:

{
  "mcpServers": {
    "hopkin-meta-ads": {
      "url": "https://meta.mcp.hopkin.ai",
      "headers": {
        "Authorization": "Bearer hpk_live_..."
      }
    }
  }
}

Key Security

• Keys are hashed (SHA-256) before storage — Hopkin never stores your raw key
• One key works across all MCP servers (Meta, Google, LinkedIn, Reddit, TikTok)
• Revoke keys immediately at app.hopkin.ai/api-keys if compromised
• Do not commit keys to version control — use environment variables or secrets managers

OAuth (JWT)

OAuth is used for browser-based flows and the Hopkin web app. When a user authenticates through app.hopkin.ai, Hopkin issues a JWT that the MCP servers accept.

When to Use OAuth

• Building a web integration that authenticates users through a browser
• Using the Hopkin web app directly
• Need per-user token refresh without managing API keys

How It Works

• User signs in at app.hopkin.ai via OAuth (Google, GitHub, or email)
• User connects their ad platform accounts (Meta, Google, LinkedIn, Reddit, TikTok) through the OAuth flow
• Hopkin issues a JWT
• The JWT is passed as a Bearer token, same as an API key: Authorization: Bearer <jwt>
• Platform-specific OAuth tokens are stored encrypted as connections and refreshed automatically

Connecting Ad Platform Accounts

Regardless of your authentication method, you need to connect your ad platform accounts before using the tools.

First-Time Setup

• Visit app.hopkin.ai
• Click Connect next to each platform you want to use
• Complete the OAuth flow for that platform (Meta, Google, LinkedIn, Reddit, or TikTok)
• Your platform tokens are stored securely and refreshed automatically

Verifying Your Connection

Use the check_auth_status tool for any platform to verify your account is connected:

{
  "tool": "meta_ads_check_auth_status",
  "params": {
    "reason": "Verify my Meta Ads connection"
  }
}

This returns your user profile, connected accounts, and token status.

Connections and Connection IDs

Each ad platform account you connect is stored as a separate connection. You can hold more than one connection per platform — a personal Meta account and an agency one, two Google Ads logins, several ChatGPT Ads API keys — and each connection has its own UUID.

Choosing which connection a tool call uses

Most tools accept an optional connection_id parameter. Resolution order:

• connection_id passed on the call — that connection is used, provided you own it or it is shared with you. Otherwise the call is rejected.
• Omitted — your default connection for that platform is used
• No default set — the first available connection is picked (ones you own before ones shared with you, newest first) and saved as your default
• Nothing available — the call returns guidance to connect the platform first

If your default connection has since been revoked or unshared, the next call resets it to another available connection and returns a warning saying so.

Connection IDs are UUIDs. Do not guess or construct them: call <platform>_list_connections to get the IDs you can use.

{
  "tool": "meta_ads_list_campaigns",
  "params": {
    "account_id": "act_123456789",
    "connection_id": "3f1a2b4c-5d6e-7f80-9a1b-2c3d4e5f6071",
    "reason": "Report on the agency account, not my personal one"
  }
}

Managing connections

Every server exposes the same six tools:

• <platform>_list_connections — every connection you can use, with its ID, display name, and whether it is your default
• <platform>_set_default_connection — set the connection used when connection_id is omitted
• <platform>_rename_connection — give a connection a display name
• <platform>_share_connection — share a connection you own with your organization
• <platform>_unshare_connection — stop sharing it
• <platform>_revoke_connection — disconnect it

Defaults are per actor: a default set with your user session and a default set with an API key are tracked separately, so an automated key and your interactive session can point at different accounts.

Shared connections

Sharing a connection makes it usable by every member of your organization. You can only share a connection you own, and only the owner can rename, unshare, or revoke it. Shared connections appear in <platform>_list_connections for other members alongside their own. Tokens are never exposed — members can call tools through a shared connection, but cannot read its credentials.

Authentication Errors

"Authentication failed": Your API key or JWT may be invalid or expired. Generate a new API key at app.hopkin.ai/api-keys.

"No <platform> account connected": You've authenticated with Hopkin but haven't connected the specific ad platform yet. Visit app.hopkin.ai to complete the platform OAuth flow, or run <platform>_check_auth_status for connection instructions.

"Token expired" from platform API: Platform tokens are refreshed automatically, but if a refresh fails, re-connect the platform at app.hopkin.ai.

"Permission denied" for a specific ad account: Your connected platform account may not have access to the requested ad account. Run check_auth_status to see which accounts are accessible, or check your permissions in the platform's native ads manager.