Authentication
Social Neuron supports three authentication methods for the MCP server and REST API. All methods produce an API key that grants access based on your plan's scope.
Authentication Methods
Device Code Flow (Recommended)
Best for local development. A browser window opens, you approve, and the CLI receives your API key automatically.
npx -y @socialneuron/mcp-server login --devicebash
How it works under the hood:
- The CLI generates a PKCE
code_verifierandcode_challenge - Your browser opens to the authorization page with the challenge
- You log in and approve the requested scopes
- The app posts the API key and state to a local callback server
- The CLI completes the PKCE exchange to activate the key
- The key is stored in your OS keychain
Browser OAuth Flow
Standard browser-based OAuth for environments that support redirects.
npx -y @socialneuron/mcp-server loginbash
API Key Paste
Generate a key in the Social Neuron dashboard and paste it into the CLI. Best for CI/CD pipelines and automated workflows.
npx -y @socialneuron/mcp-server login --pastebash
Generate your key at socialneuron.com/settings/developer.
Key Storage
API keys are stored securely using OS-native mechanisms:
| Platform | Storage | Details |
|---|---|---|
| macOS | Keychain | security add-generic-password |
| Linux | secret-tool (libsecret) | D-Bus Secret Service API |
| Windows / fallback | ~/.config/social-neuron/credentials.json | chmod 0600 |
| CI/headless | SOCIALNEURON_API_KEY env var | Highest priority |
Keys are never written to disk in plaintext. The environment variable (SOCIALNEURON_API_KEY) takes highest priority and is the recommended approach for CI/CD.
Scopes
Each API key is assigned scopes that control which operations it can perform. Scopes are determined by your subscription plan.
| Scope | Permissions |
|---|---|
mcp:full | All operations (includes all scopes below) |
mcp:read | Analytics, insights, brand profiles, content plans, quality checks, usage stats, credit balance |
mcp:write | Generate content (video, image, voiceover, carousel), create storyboards, save brand profiles, plan content |
mcp:distribute | Schedule posts, publish content plans |
mcp:analytics | Refresh analytics, YouTube deep analytics |
mcp:comments | List, reply, post, moderate, delete comments |
mcp:autopilot | Configure and monitor automated scheduling |
Scopes by Plan
| Plan | Scopes |
|---|---|
| Free | No API access |
| Trial | No API access |
| Starter ($29/mo) | mcp:read, mcp:analytics |
| Pro ($79/mo) | mcp:full |
| Team ($199/mo) | mcp:full + multi-user |
Rate Limits
Rate limits are enforced per API key:
| Plan | Requests/Minute | Max API Keys |
|---|---|---|
| Starter | 30 | 2 |
| Pro | 60 | 5 |
| Team | 120 | 20 |
Every response includes rate limit headers:
X-RateLimit-Remaining-- Requests remaining in the current windowX-RateLimit-Reset-- Unix timestamp when the window resets
Exceeding the limit returns HTTP 429. Wait until X-RateLimit-Reset before retrying.
Generation-heavy tools (video, image) have additional per-tool rate limits of 20 requests per minute to prevent runaway automation.
Security
- All API keys are SHA-256 hashed before storage -- we never store plaintext keys
- SSRF protection on all URL parameters with DNS rebinding prevention
- Agent loop detection prevents runaway automation
- Gateway token system ensures all requests flow through scope and credit enforcement
Disabling Telemetry
The MCP server collects anonymous usage metrics (tool name, duration, success/failure). Your user ID is hashed before transmission. No content, API keys, or request payloads are collected.
To disable:
export DO_NOT_TRACK=1 # or export SOCIALNEURON_NO_TELEMETRY=1bash