Skip to main content
The Ayrshare MCP Server lets an AI agent drive the Ayrshare API. This page covers how to connect to it and how authentication works.

​
Endpoint and transport

The production MCP Server is available at: https://api.ayrshare.com/mcp It uses Streamable HTTP transport and is stateless — there is no session to maintain between calls.

​
Authentication

Authentication is enforced by the same Ayrshare API chain that powers the REST API.
  • Required: Authorization: Bearer YOUR_API_KEY — your account API key (Business plan key for profiles and sub-profiles).
  • Optional: Profile-Key: YOUR_PROFILE_KEY — targets a sub-profile for every call on the connection.
  • Optional per call: a profileKey tool argument — targets a sub-profile for a single tool call.

​
Precedence: argument wins over header

When a tool call includes a profileKey argument and the connection has a Profile-Key header, the per-call profileKey argument wins. The header is used only when no valid argument is provided. One exception: on get_platform_history and get_social_network_analytics, an X/Twitter userId/userName lookup must use the account API key only; supplying a profileKey argument or Profile-Key header there returns Error 400.
The initialize and tools/list MCP methods are reachable before authentication — they return metadata only and execute nothing. Every tool call is authenticated.

​
Authentication errors

An unauthenticated or invalid key on a tool call returns an Ayrshare error 403 / code 102 with message “API Key not valid”. Per the MCP spec, tool-execution errors are returned in-band: the tool result carries isError: true and this message, while the MCP transport itself responds HTTP 200. (The 403/102 are Ayrshare’s application error, not the transport status.)

​
Connect

​
Option A: Claude Code plugin

If you use Claude Code, install the Ayrshare plugin. It bundles the MCP Server configuration, a setup command, agents, skills, and a confirmation hook. See the Claude Code Plugin page for the full install steps.

​
Option B: Any MCP client

For any MCP client that supports Streamable HTTP, register the server directly. In Claude Code: 
claude mcp add --transport http ayrshare https://api.ayrshare.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
To target a sub-profile on every call, add the optional Profile-Key header: 
claude mcp add --transport http ayrshare https://api.ayrshare.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Profile-Key: YOUR_PROFILE_KEY"
The MCP connection initializes at session start. Restart your MCP client after installing the server or changing your key so the new configuration takes effect.

​
X/Twitter BYO credentials

Since March 31, 2026, X/Twitter operations through Ayrshare require your own OAuth 1.0a credentials. When a tool call targets X/Twitter, forward these two headers on the connection alongside your Authorization (and optional Profile-Key) headers:
HeaderDescription
X-Twitter-OAuth1-Api-KeyYour OAuth 1.0a API Key (Consumer Key)
X-Twitter-OAuth1-Api-SecretYour OAuth 1.0a API Key Secret (Consumer Secret)
These are the same headers used by the REST API — one OAuth 1.0a key pair per Ayrshare account, sent on every X-targeting request (the same pair applies to all sub-profiles). Ayrshare does not use OAuth 2.0 here. See the API Overview and the X BYO Key Setup Guide for setup, policy, and troubleshooting.
Without these headers, an X/Twitter tool call returns error 419 (x_credentials_required).

​
Connect with the BYO headers

To set up X/Twitter BYO credentials from the start, add the server with both OAuth 1.0a headers alongside your Authorization header (include Profile-Key too if you target a sub-profile on every call): 
claude mcp add --transport http ayrshare https://api.ayrshare.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Twitter-OAuth1-Api-Key: YOUR_TWITTER_CONSUMER_KEY" \
  --header "X-Twitter-OAuth1-Api-Secret: YOUR_TWITTER_CONSUMER_SECRET"

​
Add the BYO headers to an existing connection

Connection headers are fixed when the server is added, so if you already connected without the BYO headers, remove the server and re-add it with the full set (re-include any headers you were already using, such as Profile-Key): 
claude mcp remove ayrshare
claude mcp add --transport http ayrshare https://api.ayrshare.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Twitter-OAuth1-Api-Key: YOUR_TWITTER_CONSUMER_KEY" \
  --header "X-Twitter-OAuth1-Api-Secret: YOUR_TWITTER_CONSUMER_SECRET"
Restart your MCP client after changing headers so the new configuration takes effect. Using the Claude Code plugin instead of a raw connection? See Claude Code Plugin → X/Twitter BYO credentials.

​
Next steps

Tool Catalog

The 27 tools grouped by domain, with scope and purpose.

Claude Code Plugin

Install the Ayrshare plugin for Claude Code.