Docs › Agents › Connect an agent

Connect an AI agent to OmniPosts over MCP with an API key

Let Claude Code, Cursor, Codex or another MCP client check, schedule and follow your posts through OmniPosts, with only the permissions you give it.

Updated

OmniPosts runs an MCP server, so an agent can check, schedule and follow your posts for you. Today an agent connects with an API key that you make for it, and it gets only the scopes you give that key.

Step 1: Make a key for the agent

In the app, open Settings, then Agents & API, and create an API key just for this agent. Give it only the scopes it needs (see Choose what it can do) and an end date. Copy the key when it is shown: it is displayed once. Keys start with omniposts_.

Step 2: Add OmniPosts to your client

The server is at https://omniposts.dev/mcp. It speaks streamable HTTP, and every call carries the key, so there is no session to start or keep.

Run this in a terminal, with your key in place of omniposts_...:

claude mcp add --transport http omniposts https://omniposts.dev/mcp \
  --header "Authorization: Bearer omniposts_..."

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in one project:

{
  "mcpServers": {
    "omniposts": {
      "url": "https://omniposts.dev/mcp",
      "headers": { "Authorization": "Bearer omniposts_..." }
    }
  }
}

Add the server to ~/.codex/config.toml, or to .codex/config.toml in a trusted project; the Codex CLI and IDE extension share it. Codex reads the key from an environment variable and sends it as Authorization: Bearer …:

[mcp_servers.omniposts]
url = "https://omniposts.dev/mcp"
bearer_token_env_var = "OMNIPOSTS_API_KEY"

Then set OMNIPOSTS_API_KEY to your key (omniposts_...) in the environment Codex starts from.

Any MCP client that speaks streamable HTTP and can send a header works. Point it at https://omniposts.dev/mcp and send Authorization: Bearer omniposts_... with every request. Many clients read a JSON config of this shape:

{
  "mcpServers": {
    "omniposts": {
      "url": "https://omniposts.dev/mcp",
      "headers": { "Authorization": "Bearer omniposts_..." }
    }
  }
}

Custom connectors in the Claude and ChatGPT apps sign in to a server with OAuth and cannot send an API key, so they cannot connect to OmniPosts yet. OAuth sign-in is coming soon. Until then, use Claude Code, Cursor, Codex or another client that can send a header.

Step 3: Ask for something

"List my channels, then check this post for Bluesky and Mastodon and queue it for the next free slot: Open studio this Saturday, 10 to 4. Bring a friend."

A few more that work well:

  • "What happened to the post I queued this morning?"
  • "Retry the channels that failed on my last post."
  • "How did yesterday's post do on Mastodon?" Numbers appear only where a platform shares them. See Honest numbers.
  • "Connect my Mastodon account." The agent cannot sign in to a platform for you: it gets a link, you open it and finish in your browser, and the agent sees the new channel when you are done.

OmniPosts tells the agent to check a post with validate_post before sending it, and never to send again a post whose outcome is unknown. OmniPosts itself never sends one post twice to the same channel.

Choose what it can do

A key does only what its scopes allow. Pick them when you create the key.

Scope What the agent can do with it
channels:read See your channels, each platform's limits and settings, and follow a connection you are finishing
posts:read Read your posts and the result on each channel
posts:write Check, send, schedule, queue, cancel and retry posts
media:write Add an image or video from a public link
metrics:read Read the numbers a platform shares about a post
channels:manage Start connecting a new channel, which you then finish in your browser

For an agent that writes and schedules posts, channels:read, posts:read, posts:write and media:write are enough. Leave posts:write out for one that should only read. posts:write covers sending right away as well as scheduling: a key cannot allow one without the other.

Some things only a signed-in person can do, such as managing API keys or deleting the account. No key can do them, so no agent can. See Authentication.

Tools the agent gets

Tool What it does Scope
list_channels Your connected channels and their health channels:read
list_providers Each platform's text and media limits and settings channels:read
validate_post Checks a post without sending it posts:write
create_post Sends a post now, at a time, or into your queue posts:write
list_posts Your posts, newest first posts:read
get_post One post, with the result on each channel posts:read
cancel_post Cancels the channels not sent yet posts:write
retry_post Sends again to the channels that can be retried posts:write
upload_media_from_url Stores an image or video from a public link media:write
start_channel_connect Starts connecting a channel and returns a link for you channels:manage
get_connect_session Whether that connection finished channels:read
get_post_metrics A post's numbers on one channel, where shared metrics:read

The tools return the same data as the API. The MCP server reference has the details.

Revoke access

Delete the agent's key in Settings, under Agents & API. From then on every call it makes is refused. A key also stops working at its end date. Posts the agent already sent stay where they are.