Authentication - Mallary.ai API, MCP, CLI Developer Docs

Mallary MCP supports OAuth 2.1 for apps and agents. Mallary API keys remain supported for scripts and existing integrations. Mallary connectors for Claude, ChatGPT, Codex, and Cursor use OAuth. They never ask the user to create, paste, or reveal a Mallary API key.

Before using the Mallary MCP Server:

Sign up at https://mallary.ai
Connect your social media accounts in the Mallary dashboard
Approve the access requested by your app, or get a Mallary API key for a manual setup

OAuth

OAuth-ready clients discover Mallary’s authorization server automatically from:

https://mallary.ai/.well-known/oauth-protected-resource

ChatGPT uses its own protected resource metadata:

https://mallary.ai/.well-known/oauth-protected-resource/mcp/openai

Mallary uses the authorization code flow with PKCE. The authorization server is:

https://auth.mallary.ai

Mallary asks the signed-in user to approve the app connection. First-party Mallary clients request the capabilities they need in one login, so the user does not choose scopes or sign in again before posting. Mallary never gives the app the user’s password or connected social account tokens. Claude can use a Client ID Metadata Document, while other clients can use Mallary’s dynamic client registration endpoint. Mallary keeps both methods available. Access tokens are short lived. Refresh tokens rotate, and revoked grants stop working. Users can review and revoke OAuth access at https://mallary.ai/oauth-connections.

Keep an App Connected

The app that runs the MCP client must renew its OAuth access tokens. Mallary cannot renew a token stored inside another app on that app’s behalf. Read the current endpoints from this discovery document. Do not guess paths such as /authorize.

https://auth.mallary.ai/.well-known/oauth-authorization-server

For a public client using dynamic registration, register both grant types and use PKCE with S256:

{
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Also supply the client’s name and exact callback URL. Use https://mallary.ai/mcp as the OAuth resource for the standard MCP endpoint. Request only the scopes the integration needs. Uploading, publishing, scheduling, and reading results need mallary.publish and mallary.read. Mallary issues refresh tokens to public PKCE clients registered for the refresh grant, even without offline_access. A registration that allows only authorization_code will not receive this capability. A client with a shared secret must also request offline_access to receive a refresh token. The connector host must:

Keep tokens and expiry details in its secure credential store. Never put them in prompts or logs.
Use the returned expires_in value to renew shortly before expiry.
Allow only one refresh at a time for each connection. Other requests must wait for that refresh.
Send grant_type=refresh_token to the discovered token endpoint with the registered client authentication and resource.
Save the new access token, rotated refresh token, and expiry together before resuming requests. Do not reuse the old refresh token.
On invalid_grant, stop and ask the user to reconnect. Do not keep retrying a revoked or expired grant.

For endpoints that issue MCP sessions, a refreshed token from the same client and grant can use the existing session. A new consent grant needs a new session. A fresh credential reference from a host’s vault does not, by itself, prove that the underlying OAuth token was renewed. Before releasing a connector, test two token renewals and a new conversation without asking the user to reconnect. If the host manages OAuth internally, the host must provide this behavior; a tool description or skill cannot add it.

OAuth Scope Reference

These scopes remain part of the OAuth protocol for client compatibility. They are not choices shown by the Mallary CLI.

mallary.read: read posts, comments, analytics, profiles, platforms, settings, and webhooks
mallary.publish: upload media and create or schedule posts
mallary.engage: reply to comments
mallary.manage: change settings, profiles, webhooks, connections, and pending posts

API Key Header

For a manual API-key setup, send the key as a bearer token:

Authorization: Bearer <mallary_api_key>

Identity Resolution

Identity is always resolved from the OAuth grant or API key owner. You do not separately pass a user ID when calling MCP tools.

Base URL

Mallary MCP is served from:

https://mallary.ai

Endpoint

Use the MCP server at:

/mcp

Use this OAuth-only endpoint for ChatGPT:

/mcp/openai

Before using the Mallary MCP Server:

​OAuth

​Keep an App Connected

​OAuth Scope Reference

​API Key Header

​Identity Resolution

​Base URL

​Endpoint