# Swell MCP Server

Endpoint: `https://api.growonswell.com/mcp`

Swell exposes a hosted JSON-RPC MCP endpoint over HTTP. Use the same workspace-scoped Swell API key as the REST API:

```http
Authorization: Bearer swl_sk_...
Content-Type: application/json
Accept: application/json
MCP-Protocol-Version: 2025-11-25
```

## Initialize

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "example-agent", "version": "1.0.0" }
  }
}
```

The server responds with protocol version `2025-11-25`, tool capabilities, and server info.

## Tools

Call `tools/list` to discover the current tool set. Current tools are:

- `swell.get_workspace`
- `swell.get_company_profile`
- `swell.refresh_company_profile`
- `swell.update_company_profile_sources`
- `swell.associate_company_profile_media`
- `swell.remove_company_profile_media`
- `swell.list_social_accounts`
- `swell.list_media`
- `swell.list_posts`
- `swell.preview_post`
- `swell.create_post`
- `swell.update_post`
- `swell.schedule_post`
- `swell.unschedule_post`
- `swell.archive_post`
- `swell.list_links`
- `swell.create_link`
- `swell.analytics_overview`
- `swell.list_people`

Tool calls use the same scope checks as REST. For example, `swell.get_company_profile` requires `profile:read`, profile mutation tools require `profile:write`, and write tools such as `swell.create_post` or `swell.schedule_post` require `posts:write`.

Mutating tools accept an optional `idempotency_key` tool argument. Reusing the same key with the same validated tool payload replays the original tool result; using the key with a different payload returns a JSON-RPC error.

## REST Pairing

Agents can mix MCP and REST safely. Use MCP for tool-native workflows, `/v1/openapi.json` for typed REST clients, and `POST /v1/posts/preview` for dry-run validation before write actions.