<!-- https://cutedyno.com/docs/mcp -->

# MCP server

Expose CuteDyno to AI agents as MCP tools — same API, same permissions, same errors as REST.

CuteDyno MCP exposes the same API as tools. Agents can list accounts, upload media through a hosted browser page, create posts, read analytics, and check status without custom integration code. Tools come from the same registry as REST, so permissions and errors match `/v1`.

## Hosted MCP endpoint

**URL:** `https://api.cutedyno.com/mcp`

Authenticate with the same Bearer API key as REST. Create one under [Developers → API](https://cutedyno.com/dashboard/api).

### Drop into Cursor or Claude MCP settings

```json
{
  "mcpServers": {
    "cutedyno": {
      "url": "https://api.cutedyno.com/mcp",
      "headers": { "Authorization": "Bearer cdyn_live_..." }
    }
  }
}
```

### Stdio (local)

Spawn a local process when your runtime cannot call HTTP MCP.

```bash
npx -y cutedyno mcp
```

## Tools

Tool detail pages are linked from this index (they are not listed in the sidebar).

### Profiles

- [`list_profiles`](https://cutedyno.com/docs/mcp/tools/list_profiles) *(read only)* — Lists every profile this API key can act on. Start here when the key serves multiple customers, then pass profileId to the other tools.
- [`create_profile`](https://cutedyno.com/docs/mcp/tools/create_profile) — Creates a profile for a new customer. Requires an account-wide API key.
- [`get_profile`](https://cutedyno.com/docs/mcp/tools/get_profile) *(read only)* — Returns the profile this request resolves to, including its name and description.
- [`update_profile`](https://cutedyno.com/docs/mcp/tools/update_profile) — Renames a profile or changes its description.

### Accounts

- [`list_accounts`](https://cutedyno.com/docs/mcp/tools/list_accounts) *(read only)* — Returns the social accounts connected to a profile. Use each `id` in accountIds when creating a post, and `accountId` when filtering comments.
- [`start_connect`](https://cutedyno.com/docs/mcp/tools/start_connect) — Starts a hosted OAuth flow and returns authUrl plus a session id. Send the user to authUrl; the account appears in list_accounts once they finish.
- [`create_connect_session`](https://cutedyno.com/docs/mcp/tools/create_connect_session) — Starts an OAuth flow for one profile and returns the URL to redirect your customer to. Equivalent to start_connect for most agents.
- [`get_connect_session`](https://cutedyno.com/docs/mcp/tools/get_connect_session) *(read only)* — Checks whether a connect flow finished. Prefer the connection.completed webhook over polling this.

### Posts

- [`list_posts`](https://cutedyno.com/docs/mcp/tools/list_posts) *(read only)* — Returns posts for a profile, newest first, with filters for status, content type, and platform.
- [`get_post`](https://cutedyno.com/docs/mcp/tools/get_post) *(read only)* — Returns one post with its content, media, target accounts, and per-account publish results.
- [`create_post`](https://cutedyno.com/docs/mcp/tools/create_post) — Creates a post. Omit publishNow and scheduledAt to save a draft, set scheduledAt to schedule, or set publishNow to publish right away.
- [`update_post`](https://cutedyno.com/docs/mcp/tools/update_post) — Edits a draft or scheduled post. Published, processing, and partially published posts cannot be edited.
- [`cancel_post`](https://cutedyno.com/docs/mcp/tools/cancel_post) — Cancels a scheduled or queued post before it publishes.
- [`validate_post`](https://cutedyno.com/docs/mcp/tools/validate_post) *(read only)* — Dry-runs the same checks as create_post without writing anything. Use it before creating a post you are unsure about.
- [`publish_post`](https://cutedyno.com/docs/mcp/tools/publish_post) — Moves a draft into the publishing queue. When the profile requires approval and you pass approvers, the post waits for them instead.
- [`retry_post`](https://cutedyno.com/docs/mcp/tools/retry_post) — Requeues a failed or partially published post. Only the accounts that failed are retried.
- [`get_post_history`](https://cutedyno.com/docs/mcp/tools/get_post_history) *(read only)* — Returns every state transition for a post. This is the fastest way to explain why something failed.

### Comments

- [`list_comments`](https://cutedyno.com/docs/mcp/tools/list_comments) *(read only)* — Returns comments on a profile’s published content. Facebook and Instagram only.

### Media

- [`upload_media`](https://cutedyno.com/docs/mcp/tools/upload_media) — Returns a presigned URL for programmatic uploads. PUT the file bytes to signedUrl, then pass publicUrl in a post. For AI clients without file access, use create_upload_session instead.
- [`create_upload_session`](https://cutedyno.com/docs/mcp/tools/create_upload_session) — Returns uploadUrl for the user to open in a browser and upload images or video. Poll get_upload_session until status is completed, then use files[].url in create_post.
- [`get_upload_session`](https://cutedyno.com/docs/mcp/tools/get_upload_session) *(read only)* — Checks whether a browser upload finished. When status is completed, files contains the public URLs to attach to a post.

### Analytics

- [`get_analytics`](https://cutedyno.com/docs/mcp/tools/get_analytics) *(read only)* — Returns current account metrics and recent content across connected platforms for a profile.
- [`get_analytics_history`](https://cutedyno.com/docs/mcp/tools/get_analytics_history) *(read only)* — Returns snapshot-based timeseries, platform breakdown, top content, and insights for a date range.

### Webhooks

- [`list_webhooks`](https://cutedyno.com/docs/mcp/tools/list_webhooks) *(read only)* — Returns the webhook endpoints registered for a profile.
- [`create_webhook`](https://cutedyno.com/docs/mcp/tools/create_webhook) — Registers an endpoint to receive events. Set scope to account to receive events from every profile through one endpoint.
- [`test_webhook`](https://cutedyno.com/docs/mcp/tools/test_webhook) — Delivers a synthetic event so the receiver can be verified before real activity happens.
- [`list_webhook_deliveries`](https://cutedyno.com/docs/mcp/tools/list_webhook_deliveries) *(read only)* — Returns the delivery log for one subscription, with response codes, attempt counts, and the next scheduled retry.
- [`delete_webhook`](https://cutedyno.com/docs/mcp/tools/delete_webhook) — Removes a webhook endpoint. In-flight retries stop.

### Policy

- [`get_policy`](https://cutedyno.com/docs/mcp/tools/get_policy) *(read only)* — Returns the guardrails on a profile: whether approval is required, which platforms are allowed, and the daily post cap. Check this before publishing.
- [`update_policy`](https://cutedyno.com/docs/mcp/tools/update_policy) — Changes a profile’s guardrails. Only the fields you send are modified.

### Observability

- [`list_events`](https://cutedyno.com/docs/mcp/tools/list_events) *(read only)* — Returns the audit trail for a profile: which actions were taken, and whether by a key, an agent, or a person.
- [`list_logs`](https://cutedyno.com/docs/mcp/tools/list_logs) *(read only)* — Returns recent API calls against a profile with status codes, durations, and request ids. Use it to debug a failing integration.

Read-only tools are safe to auto-approve. Writes can publish to live accounts.

## Resources and prompts

| URI | Contents |
| --- | --- |
| `cutedyno://docs/workflow` | How to go from a connected account to a published post |
| `cutedyno://docs/content-types` | Payload shapes for text, image, and video posts |
| `cutedyno://docs/errors` | What each error code means and whether to retry |

| Prompt | What it does | Arguments |
| --- | --- | --- |
| `draft-social-post` | Write a post for one platform and create it as a draft in CuteDyno | platform, topic, tone? |
| `weekly-content-plan` | Plan a week of posts and create them as drafts | themes, platforms |
| `audit-recent-activity` | Summarise what happened on a profile and flag failures | profileId? |

## Guardrails

1. Prefer a dedicated key per agent or environment so you can revoke one without taking everything down.
2. Limit with `profileIds`, `allowedAccountIds`, and `maxPostsPerDay` when the caller is an LLM.
3. Require human approval through profile policy — call `get_policy` or set `requireApproval` with [`PUT /v1/policy`](/docs/api/update-policy).

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| No tools | Config JSON invalid, or `servers` vs `mcpServers` mismatch. Run `npx -y cutedyno mcp --tools` with your API key set. |
| `invalid_api_key` | Key missing, revoked, or has stray whitespace. |
| `insufficient_permission` | Key lacks access for that action. |
| Unexpected drafts | Profile requires approval. Call `get_policy`. |
| Local API failures | Set `CUTEDYNO_API_URL` (e.g. `http://localhost:3000`). |