# Connect your AI agent to Wahlu

**If you're a person:** copy [wahlu.com/connect](https://wahlu.com/connect) and give it to your AI agent. It reads this guide, sets up what it can and tells you when it needs you. You can also follow the steps yourself. **If you're an AI agent:** the same guide is plain markdown at [https://wahlu.com/connect.md](https://wahlu.com/connect.md).

## For the agent

Wahlu is a social media scheduler: it holds a person's brands, media, drafts and publishing calendar for Instagram, Facebook, TikTok, YouTube and LinkedIn personal profiles. Once connected, you can read that context, add media, create drafts, check they're ready and schedule them.

Work through the steps below in order. Where a step needs the person, stop and tell them exactly what to do. Never ask for their Wahlu password, and never ask them to paste an API key into the conversation.

## 1. The MCP server

- URL: `https://mcp.wahlu.com/mcp`
- Transport: Streamable HTTP.
- Sign-in: OAuth in the person's browser. Wahlu identifies clients by their Client ID Metadata Document (CIMD). It does not support dynamic client registration (DCR), and this URL does not take API keys.

## 2. Add Wahlu to your client

Work out which client you're running in and follow its section. These steps were checked against each vendor's documentation on 24 September 2026; menus can change, so if one doesn't match, ask the person what they see. Wahlu's Claude and ChatGPT directory apps are coming soon, so don't look for Wahlu in either directory: add it as a custom connector.

### Claude (claude.ai and Claude Desktop)

The person adds a custom connector in Claude's settings. You can't do this for them. Tell them:

1. Open **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Name it Wahlu and paste `https://mcp.wahlu.com/mcp` as the remote MCP server URL. Leave **Advanced settings** empty.
4. Click **Add**, then **Connect**, and sign in to Wahlu (step 3 below).
5. In a chat, turn Wahlu on from the **+** button under **Connectors**.

The same steps work on claude.ai and in Claude Desktop. On Team and Enterprise plans, an organisation owner first adds the connector in **Organization settings → Connectors** (**Add**, then **Custom → Web**); members then click **Connect** next to it in **Customize → Connectors**. Free plans allow one custom connector. Source: [Claude Help Center](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### ChatGPT

The person adds Wahlu on the ChatGPT website with developer mode. The ChatGPT desktop apps don't have this setting. Tell them:

1. On [chatgpt.com](https://chatgpt.com), open **Settings → Security and login** and turn on **Developer mode**.
2. Go to [chatgpt.com/plugins](https://chatgpt.com/plugins) and select the **+** button.
3. Name it Wahlu, paste `https://mcp.wahlu.com/mcp` as the MCP server URL and choose **OAuth** if asked how to authenticate.
4. Create the connection and sign in to Wahlu when asked (step 3 below).
5. Start a new conversation and add Wahlu from the tools menu.

Whether developer mode is available depends on the person's ChatGPT plan and workspace settings; a workspace admin may need to allow it. Source: [OpenAI developer docs](https://developers.openai.com/plugins/deploy/connect-chatgpt).

### Claude Code

If you can run shell commands, run this yourself. Otherwise give it to the person:

```bash
claude mcp add --transport http wahlu https://mcp.wahlu.com/mcp
```

This adds Wahlu to the current project. To use it in every project, add `--scope user` before `wahlu`. Then the person runs `/mcp` in Claude Code, selects wahlu and signs in to Wahlu in the browser that opens. If Wahlu's tools still aren't available to you, ask them to start a new Claude Code session. Source: [Claude Code docs](https://code.claude.com/docs/en/mcp).

### VS Code

Add this to `.vscode/mcp.json` in the workspace, or to the user configuration (command: **MCP: Open User Configuration**). The person can also run **MCP: Add Server**, choose **HTTP** and paste the URL.

```json
{
  "servers": {
    "wahlu": {
      "type": "http",
      "url": "https://mcp.wahlu.com/mcp"
    }
  }
}
```

When the server starts, VS Code asks the person to sign in to Wahlu. Source: [VS Code docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

### Cursor and clients that need dynamic client registration

When this guide was checked, Cursor signed in to remote MCP servers with dynamic client registration or a fixed client ID, not a Client ID Metadata Document, so it can't sign in to the hosted URL. The same applies to any client that reports "dynamic client registration not supported". Use the local Wahlu MCP server instead. It runs on the person's computer with Node.js and a Wahlu API key. For Cursor, add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "wahlu": {
      "command": "npx",
      "args": ["-y", "@wahlu/mcp-server@latest"],
      "env": {
        "WAHLU_API_KEY": "paste-your-key-here"
      }
    }
  }
}
```

Ask the person to create a key in the Wahlu app under **Settings → API Keys** in their workspace, with only the permissions and brands you need, and to paste it into the file themselves. Keep keys out of project files that are committed. Other clients use the same `command`, `args` and `env` values in their own format. The local server has the same tools, plus `upload_media_from_file` for files on that computer. Source: [Cursor docs](https://cursor.com/docs/context/mcp).

### Other MCP clients

If the client supports remote Streamable HTTP servers with OAuth and CIMD, add `https://mcp.wahlu.com/mcp` with OAuth sign-in. If not, use the local server above.

### No MCP? Use the REST API or CLI

- REST API: `https://api.wahlu.com/v1` with a Wahlu API key as a Bearer token. Start with the [API docs](https://wahlu.com/docs) and the [held schedule recipe](https://wahlu.com/docs/recipes/held-schedule).
- CLI: `npm install --global @wahlu/cli` (Node.js 20 or later), then set `WAHLU_API_KEY` and run `wahlu auth status`. It covers discovery, media import, drafts, readiness checks and schedules.

## 3. What the person sees at sign-in

When the client connects, a Wahlu page opens in the person's browser. Tell them what to expect:

1. **Continue as:** confirm the Wahlu account, or choose **Use a different account**.
2. **Choose a workspace.**
3. **Choose brands:** if the workspace has one brand it's already ticked; otherwise tick the brands you should work with.
4. **Permissions:** every permission you requested starts ticked, and the person can untick any of them. Permissions that change data or publish are labelled.
5. Select **Allow access**.

Agent access needs a Wahlu plan that includes it, and at least one brand. If the account can't connect yet, the page says why. A workspace owner can upgrade or create a brand from there; afterwards the Wahlu app shows **You're ready to connect your AI app** with a **Continue** button that returns them to the same sign-in to finish. Anyone else should ask the workspace owner, or switch to another account.

## 4. Check the connection works

1. Call `get_context`. It's read-only and needs no permission. It returns the workspace, the brands you can use and the permissions you were granted.
2. Tell the person which workspace and brands you can see and which permissions you have. If there's more than one brand, ask which one to use.
3. Optionally call `list_targets` with that brand's `brand_id` to see its connected social accounts. It needs the **See connected social accounts** permission.

Don't create, upload or schedule anything just to test the connection. If no Wahlu tools are available, the connector isn't added or isn't turned on for this conversation. If a tool returns an authorisation error, ask the person to reconnect and check the brands and permissions they chose.

## 5. When to hand over to the person

- Adding the connector in Claude or ChatGPT settings, or approving a config change in their editor.
- Signing in to Wahlu and choosing the workspace, brands and permissions.
- Upgrading the plan or creating a brand.
- Creating an API key for the local server, REST API or CLI.
- Connecting or reconnecting a social account. Do this in the Wahlu app; `list_targets` shows which accounts need attention.
- Approving a schedule you created for review.
- Disconnecting you, at [auth.wahlu.com/connections](https://auth.wahlu.com/connections).

## 6. Scheduling, publishing and review

- Scheduling and publishing are separate permissions. **Manage your schedule** (`schedule:write`) lets you check drafts and create, reschedule or cancel schedules. **Publish to social accounts** (`publish:execute`) lets scheduled posts go out and is needed for approved schedules, rescheduling and removing posts this connection published.
- Run `preflight_draft` before scheduling. It changes nothing and reports whether the draft is ready for the chosen accounts.
- Create schedules with `approval_status` set to `pending_review` unless the person has clearly asked you to publish. A held schedule creates no job and can't publish until a person approves it in the Wahlu calendar.
- An `approved` schedule needs `publish:execute` and can publish at its scheduled time without further review. Only use it when the person has said so.
- When a tool takes an `idempotency_key`, reuse the same key when you retry the same request so nothing is duplicated.
- The hosted server can't read files on the person's computer. Use `import_media_from_url`, or `upload_media` for an image or video you hold as data.
- Queue management, general edits to existing drafts and approvals stay in the Wahlu app.

## Tools

- Discovery: `get_context`, `list_targets`, `get_platform_capabilities`, `get_target_dynamic_options`.
- Media: `list_media`, `get_media`, `import_media_from_url`, `upload_media`, `create_media_repair_derivative`.
- Content: `list_content_items`, `get_content_item`, `create_draft`, `update_draft_tiktok_privacy`, `preflight_draft`.
- Schedules: `list_schedules`, `get_schedule`, `create_schedule`, `reschedule_schedule`, `cancel_schedule`, `get_publish_run_receipt`, `cleanup_provider_publications`.

Full reference: [MCP server docs](https://wahlu.com/docs/mcp-server).