# Developer API


Social Neuron provides 91 tools via the **Model Context Protocol (MCP)** server. Control the complete content lifecycle from Claude Code, Claude Desktop, or any MCP-compatible client using natural language.

## Quick Start

### 1. Authenticate

```bash
npx -y @socialneuron/mcp-server login --device
```

A browser window opens for authentication and the CLI receives your API key automatically.

### 2. Add to Claude Code

```bash
claude mcp add socialneuron -- npx -y @socialneuron/mcp-server
```

### 3. Start Using

Ask Claude: "Generate 5 content ideas about sustainable fashion" -- Claude will use the registered MCP tools to execute the request.

:::tip
MCP API access requires a Pro plan or higher (a 14-day trial also includes full MCP access). Pro ($49/mo) includes Read, Write, Distribute + Analytics scopes. Team ($99/mo) and Agency ($249/mo) include full MCP access plus Autopilot. Starter ($19/mo) does not include MCP — upgrade to Pro for API access. See the [MCP Quickstart](/docs/guides/mcp-quickstart) for detailed setup instructions.
:::

## What You Can Do

Ask Claude things like:

- "Generate 5 content ideas about sustainable fashion for Gen Z"
- "Create a 30-second video ad for my product launch"
- "Schedule this image to Instagram and LinkedIn at 9am tomorrow"
- "Show me my best-performing content this month"
- "Set up autopilot to post 3 times per week"

## Tool Categories

91 tools across 26 modules covering the full content lifecycle:

| Category | Tools | What It Does |
|----------|-------|-------------|
| Ideation | 4 tools | AI-powered content ideas and trend research |
| Content | 6 tools | Video, image, voiceover, and carousel creation with AI model families |
| Distribution | 5 tools | Multi-platform publishing, scheduling, and slot optimization |
| Analytics | 2 tools | Performance tracking across all platforms |
| Insights | 2 tools | Data-driven content optimization |
| Brand | 4 tools | Brand identity and voice management |
| Comments | 5 tools | Social engagement management |
| Planning | 5 tools | Content calendar and approval workflows |
| Autopilot | 3 tools | Automated content scheduling |
| Quality | 2 tools | Pre-publish content validation |
| Credits | 2 tools | Usage and budget tracking |

For the full tool reference with parameters and response schemas, see the [MCP Tools API](/tools-api).


## Authentication Methods

| Method | Best For | How |
|--------|----------|-----|
| **Device Code** (recommended) | Local development | `npx @socialneuron/mcp-server login --device` |
| **Browser Flow** | Environments with browser access | `npx @socialneuron/mcp-server login` |
| **API Key Paste** | CI/CD and automated workflows | `npx @socialneuron/mcp-server login --paste` |

API keys are stored securely in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). They are never written to disk in plaintext.

See the [Authentication Guide](/docs/guides/authentication) for full details.

## Scopes

| Scope | Description |
|-------|-------------|
| `mcp:full` | All operations |
| `mcp:read` | Read content, brand profiles, plans, settings |
| `mcp:write` | Create and edit content, brand profiles, plans |
| `mcp:distribute` | Schedule, publish, and manage posts |
| `mcp:analytics` | Read analytics, insights, and performance data |
| `mcp:comments` | Read, reply, moderate, and delete comments |
| `mcp:autopilot` | Configure and manage automated scheduling |

## Rate Limits

Limits are layered — a request must clear every layer that applies:

| Layer | Limit |
|-------|-------|
| Per-user (all paid tiers) | 100 requests/min |
| Per-user (14-day trial) | 15 requests/min |
| Video generation | 5 requests/min |
| Image generation | 10 requests/min |
| Text generation | 30 requests/min |
| `schedule_post` | 10 requests/min |
| Per-IP (before auth) | 60 requests/min |
| Account-wide session cap | 500 calls/hour |

See the [MCP Tools API](/tools-api) and [REST API rate-limits section](/rest-api) for the full breakdown, including why read/poll-heavy tools are weighted lighter against the session cap.

Rate limit headers (`X-RateLimit-Remaining`, `X-RateLimit-Reset`) are included in every response. Exceeding the limit returns HTTP 429.

## Error Reference

| Code | Cause | Fix |
|------|-------|-----|
| 401 | API key expired or invalid | Re-authenticate with `login --device` |
| 402 | Insufficient credits | Purchase credits or upgrade plan |
| 403 | Missing required scope | Generate new key with correct scopes |
| 404 | Resource not found | Verify ID with a list operation first |
| 422 | Invalid parameters | Check parameter types in the [MCP Tools API](/tools-api) |
| 429 | Rate limited | Wait until `X-RateLimit-Reset`, then retry |
| 500 | Server error | Retry once; report if persistent |

## Agent Discovery Resources

- [system-prompt.txt](https://socialneuron.com/system-prompt.txt) -- Copy-pasteable agent protocol
- [llms-full.txt](https://socialneuron.com/llms-full.txt) -- Full product and API reference
- [.well-known/ai-plugin.json](https://socialneuron.com/.well-known/ai-plugin.json) -- Agent discovery manifest