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.

​
Supported clients

The Action MCP Server authenticates only with a static Authorization: Bearer request header. That one requirement decides everything below: a client that can set a custom HTTP header on a Streamable HTTP connection can authenticate, and a client that cannot, cannot. Find your client before you start setup.

​
Why personal connectors cannot authenticate

Ayrshare’s Action MCP requires a static Authorization: Bearer header. Adding it as a personal custom connector on claude.ai, Claude Desktop, or Claude mobile does not work, because Ayrshare publishes no OAuth metadata and the request-header alternative is a beta limited to approved organizations. On a personal connector, no setting on your side fixes this: there is no field for an Authorization header, and no API key, profile, or account setting that enables one. Ayrshare does not publish OAuth metadata, so the connector’s OAuth path has nothing to connect to. Use a client from the table above instead: Claude Code, the Claude Code plugin, or any client that lets you set a custom Authorization header. If you are an administrator of an organization in Anthropic’s request-header beta, see Team and Enterprise organizations below.
If your connector looks healthy but every tool fails. The connector adds cleanly, reports healthy, and lists the full tool catalog — and then every tool call returns Ayrshare 403 / code 102, “API Key not valid”. That is this limitation, not a broken key — your client cannot send the static Authorization: Bearer header this server requires. initialize and tools/list are reachable before authentication (see Authentication below), so nothing fails until the first tool call, when it becomes clear no credential was ever sent.Client capability, or a genuinely bad key? They return the identical error, so use the signature to tell them apart. A client-capability failure means the connector is healthy and every tool fails, while the same key works elsewhere. A bad key produces the same error but is reproducible outside the connector — it fails on a REST call too. For the error semantics themselves, see Authentication errors below.

​
Team and Enterprise organizations

Anthropic’s static_headers mechanism lets a custom connector send a fixed credential as a request header instead of using OAuth. It is available in beta to organization administrators in a limited set of organizations, and it is not available to individual users adding a personal connector. If your organization has access, the administrator must enter the header value as Bearer followed by your Ayrshare API key, including the space — Claude sends the value exactly as entered and does not add the scheme for you. For current availability and setup, see Anthropic’s connector authentication documentation.
The key is shared by the whole organization. Anthropic’s request-header credential is entered once by an administrator and used by every member of the organization, so all of them act as the single Ayrshare account that key belongs to — with access to every User Profile under it on a Business key, and no per-user attribution in your Ayrshare history or analytics. Treat it as a shared service credential, not as individual access.

​
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 and lets you set a custom request header — see Supported clients above — register the server directly. In Claude Code:
To target a sub-profile on every call, add the optional Profile-Key header:
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: 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):

​
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):
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.