Skip to content

Agent setup

Connect your AI agent to Wahlu

Wahlu is one place for your social media, and your agent can use it too. Copy this link and give it to your AI agent: it follows the steps below, sets up what it can and tells you when it needs you.

For agents: the same guide is plain markdown at 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, LinkedIn personal profiles, X, Bluesky, Telegram, Discord and Tumblr. 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.
  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.

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, open Settings → Security and login and turn on Developer mode.
  2. Go to 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.
  5. Start a new conversation and add Wahlu from the tools menu.

Set this up on the ChatGPT website; the desktop apps don't have developer mode. Whether developer mode is available depends on your ChatGPT plan and workspace settings, and a workspace admin may need to allow it.

Source: OpenAI developer docs.

Claude Code

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

claude mcp add --transport http wahlu https://mcp.wahlu.com/mcp
  1. Run claude mcp add (the command shown here) in your project.
  2. In Claude Code, run /mcp, select wahlu and sign in to Wahlu in the browser that opens.

This adds Wahlu to the current project. To use it in every project, add --scope user before wahlu. If Wahlu's tools don't appear, start a new Claude Code session.

Source: Claude Code docs.

Codex

If you can run shell commands, run the first command yourself. The person signs in with the second:

codex mcp add wahlu --url https://mcp.wahlu.com/mcp
codex mcp login wahlu
  1. Run codex mcp add to add Wahlu. It's saved in ~/.codex/config.toml, which the Codex CLI, IDE extension and app share.
  2. Run codex mcp login wahlu and sign in to Wahlu in the browser that opens.
  3. Start a new Codex session so it picks up Wahlu's tools.

In the Codex IDE extension or app you can add it from the gear menu instead: MCP servers → Add server, choose Streamable HTTP and paste the URL, then restart. Codex signs in with a Client ID Metadata Document, which is what Wahlu uses.

Source: Codex docs, checked 27 September 2026.

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.

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

When the server starts, VS Code asks you to sign in to Wahlu.

Source: VS Code docs.

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:

{
  "mcpServers": {
    "wahlu": {
      "command": "npx",
      "args": ["-y", "@wahlu/mcp-server@latest"],
      "env": {
        "WAHLU_API_KEY": "paste-your-key-here"
      }
    }
  }
}
  1. In the Wahlu app, create an API key under Settings → API Keys in your workspace, with only the permissions and brands you need.
  2. Add the Wahlu configuration to ~/.cursor/mcp.json and paste the key into it yourself.
  3. Restart Cursor, or refresh its MCP servers, so it starts the Wahlu server.

Cursor can't sign in to the hosted URL yet, because it doesn't support Client ID Metadata Documents. The local server runs on your computer. Available tools depend on the installed version, so check the local MCP server notes before relying on a tool listed for the hosted server. Keep the key out of project files that are committed.

Never ask the person to paste the key into the conversation. Other clients use the same command, args and env values in their own format.

Source: Cursor docs, checked 27 September 2026.

Gemini CLI

Gemini CLI can't sign in to the hosted URL: it registers with dynamic client registration, which Wahlu doesn't support. Use the local Wahlu MCP server with a Wahlu API key instead. The person exports the key in their shell, then you add this to the mcpServers object in ~/.gemini/settings.json, keeping any settings already in the file:

{
  "mcpServers": {
    "wahlu": {
      "command": "npx",
      "args": ["-y", "@wahlu/mcp-server@latest"],
      "env": {
        "WAHLU_API_KEY": "$WAHLU_API_KEY"
      }
    }
  }
}
  1. In the Wahlu app, create an API key under Settings → API Keys in your workspace, with only the permissions and brands you need.
  2. Add export WAHLU_API_KEY=your-key to your shell profile, with your key, and open a new terminal.
  3. Add the Wahlu configuration to ~/.gemini/settings.json. If the file already has settings, add wahlu inside its mcpServers object.
  4. Start a new Gemini CLI session and run /mcp to check that wahlu is connected and its tools are listed.

Gemini CLI replaces $WAHLU_API_KEY with the value from your shell, so the key isn't saved in the settings file. You can also add the same configuration to a project's .gemini/settings.json to use Wahlu in that project only. Available local tools depend on the installed version. Check the local MCP server notes for its Node.js requirement and tool availability.

Never ask the person to paste the key into the conversation. gemini mcp list shows whether the server is configured and connected.

Source: Gemini CLI docs, checked 27 September 2026.

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 and the held schedule recipe.
  • 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. Available commands depend on the installed version; check wahlu --help and the CLI guide.

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.
  • Getting clear approval before using approve_schedule on a held post. This tool also needs Publishing permission and confirmation of the exact schedule ID.
  • Disconnecting you, at 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. Publishing (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 it is approved in the Wahlu calendar or through approve_schedule with Publishing permission and the person's explicit approval.
  • Autopilot posts can have lines to check: brand details Wahlu couldn't verify, such as a price, opening hours or a story. approve_schedule refuses such a post and names the lines. Show them to the person, then fix them with resolve_autopilot_fact_flag (use the suggestion or remove the line; mark one true only when the person says it is), or in Wahlu. Set acknowledge_fact_flags only after the person has seen the lines and still wants the post approved.
  • 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.
  • Use update_draft to change the name or caption of an unused draft. Draft edits and deletion, and schedule approval, deletion or moving to drafts, need confirmation of the exact item ID. Queue management, draft media changes and most platform settings stay in the Wahlu app.

Tools

  • Discovery: get_context, get_brand_context, list_labels, list_targets, get_platform_capabilities, refresh_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, list_drafts, update_draft, delete_draft.
  • Schedules: list_schedules, get_schedule, create_schedule, reschedule_schedule, cancel_schedule, get_publish_run_receipt, cleanup_provider_publications, approve_schedule, move_schedule_to_draft, delete_schedule.
  • History: list_history.
  • Link in bio: get_bio_page, get_bio_stats.
  • Autopilot: get_autopilot_plan, get_autopilot_week, approve_autopilot_item, regenerate_autopilot_item, resolve_autopilot_fact_flag.
  • Notifications: list_notifications.

Full reference: MCP server docs.