MCP authorization, project selection, and discovery

Connect to https://api.rightmessage.com/mcp/rightmessage with hosted OAuth using the mcp:use scope, or with an API token in the Authorization: Bearer header. The connection acts for your user account; each project operation still checks project access and eligibility. For setup steps, see Connect RightMessage to your AI assistant.

Hosted connection

A request without a valid credential gets a JSON 401, whatever the client's Accept header. It never redirects to the sign-in page. Its WWW-Authenticate header is Bearer realm="mcp", resource_metadata="https://api.rightmessage.com/.well-known/oauth-protected-resource/mcp/rightmessage", which points the client to the protected resource metadata so it can start OAuth.

The public discovery documents identify these OAuth endpoints.

The client handles registration, PKCE, token exchange, and refresh. These aren't project-management tools, and calling a tool before authorization doesn't replace that flow.

OAuth access tokens are issued for 60 minutes and refresh tokens for one year. The client should refresh access rather than ask you to create another API token. Disconnecting the client revokes its access and refresh tokens before those expiry times.

Discovery metadata is limited to 120 requests per minute per IP address. Dynamic client registration is limited to 10 requests per minute and 100 per day per IP address. These are separate from the hosted MCP request limit.

Server card

The server card is a public JSON description of the hosted server, for MCP registries and clients that look a server up before connecting. It names the server com.rightmessage/mcp, with the title RightMessage, and gives:

• The server version, the same one the server reports when a client connects.
• One remote: the Streamable HTTP endpoint https://api.rightmessage.com/mcp/rightmessage.
• The MCP protocol versions the server supports.
• Icons and the MCP setup page.

It needs no credential, any website can fetch it, and it can be cached for an hour. https://rightmessage.com/.well-known/mcp/server-card.json serves the same document. The card describes the server; you still sign in and approve access to connect.

Approval and identity

The consent page shows Signed in as, Application, Redirect host, and Requested permission. Approve authorizes the displayed application. Cancel denies the request. The page follows the operating system's color scheme.

Enlarge

RightMessage OAuth approval for WorkForge Assistant, signed in as docs-developer@example.com, requesting mcp:use permissionOriginalOriginal

OAuth grants permission to use MCP on your behalf. It is not a per-project or read-only grant. Project membership, account suspension, project eligibility, and feature-specific checks still apply.

A bearer token authenticates the same user-level relationship, limited by the token's abilities. See API token abilities.

API token abilities

An API token's read, write, and publish abilities decide which tools a manual bearer connection can use. OAuth connections have no abilities and aren't limited this way. Tokens created on the API & AI access page have full access (*), so they see every tool.

A tool's read-only hint decides whether it needs read or write, because every MCP call is the same kind of request. publish-config and unpublish-page change the live site at once, so they need publish, the same as the REST publish endpoint. The Meta Ads mapping tools change your project and put the change live in one call, so they need both write and publish. Prompts and the configuration overview resource aren't tools and stay available.

tools/list leaves out the tools the token can't call, so your assistant isn't offered actions that would only fail. If a client calls one anyway from a list it cached earlier, it gets a tool error that names the missing ability and nothing changes:

This API token can't make changes: it needs the `write` ability. Create a token with it under Your account › API & AI access.

A read-only tool refused for a publish-only token says can't read project data and names read, and a publish tool says can't publish and names publish. Abilities don't limit which projects the token reaches.

Eligible projects

MCP access and API-token creation are separate entitlements. MCP access comes with every plan, while creating an API token requires Scale or Pro. Hosted OAuth doesn't require creating an API token. An eligible subscription, an active entitlement, or supported legacy access can provide MCP access.

A project whose 14-day trial hasn't started yet, because its billing setup didn't finish, can still be eligible for MCP. During a no-card trial, the project has every Pro feature through MCP too. A lapsed subscription doesn't automatically retain MCP access. When a no-card trial ends without a confirmed plan, the project's AI-agent (MCP) access is locked until the owner adds a card, so the project can't be selected.

Authorization has two stages. The connection requires at least one eligible project. Each project tool then checks access to the project it resolves. A successful connection doesn't mean every project or feature in the account is available.

Supported client connections

These are connection methods and accepted callback origins, not promises about a third-party subscription or menu layout.

A callback origin must be supported even when the server URL is correct. Changing a callback to an arbitrary website isn't a substitute for compatible client support.

Project selection

Most project tools resolve a project in this order.

1. The request's explicit project_id.
2. The connection's remembered active project.
3. The only eligible project, if exactly one is available.
4. The user's current dashboard project, if eligible.

If none resolves, the tool returns an error asking for project_id or set-active-project. A malformed ID, inaccessible project, or ineligible project returns an error rather than silently selecting a different one.

Project IDs are the public IDs visible in dashboard URLs. You can also copy one by opening Project settings (the gear at the bottom of the sidebar), then General. Resource IDs, such as a flow or question ID, come from the matching list or get tool. Names aren't interchangeable with IDs.

set-active-project remembers the choice for the connection. An explicit project_id overrides that default for the individual call. Selection changes which integration-dependent tools are discoverable. It doesn't change the project's configuration or restrict what projects the credential could access.

There is no registered list-projects tool. The configuration overview resource and project context tools provide the supported discovery and readback path.

Tool discovery

The public catalog contains 173 tools. Two connections add tools: Senja adds list-apps and get-app-resources, and Stripe adds get-segment-revenue. A project without Senja exposes 171 tools, without Stripe 172, and without either 170. A manual bearer connection whose token doesn't have every ability sees fewer, as API token abilities explains.

The count includes 25 page tools for Pages, which every project can use.

The server advertises tools.listChanged. Successful integration connection and active-project changes can notify the client to rediscover tools. A client with a cached list may need an explicit refresh or reconnection.

Each registered tool supplies a name, argument schema, title, and hints about read-only, destructive, or external effects. For a manual bearer connection, the read-only hint decides which ability a tool needs. Otherwise the hints are advisory, not a guarantee that the implementation never contacts an external service. Review the tool's arguments and documented effects before allowing it to run.

The reference family pages list the actual hyphenated tool names. For example, use get-analytics-overview, not get-overview. Tools used internally by Righty aren't automatically available to external assistants.

Drafts and other side effects

Most configuration mutations change the project draft. publish-config is a separate operation and affects the complete publishable draft, not only the assistant's last edit.

Other tools have different boundaries. Exports start jobs. Integration operations can change provider state. Feedback queues immediately. Personalized emails are saved records. Split tests have their own lifecycle. Lead alert rules take effect as soon as they're saved, with no draft. The individual tool references identify these effects.

Connection list and revocation

Open Your account (the avatar at the bottom of the sidebar), then API & AI access. The AI assistants section lists OAuth clients, each with its name and the date it connected. Connections with a usable refresh token can remain listed after an access token expires.

Enlarge

AI assistants on API & AI access listing example Claude and ChatGPT connections with their connected dates and Disconnect buttonsOriginalOriginal

Disconnect opens a Disconnect client name? confirmation. Confirming Disconnect revokes that user's access and refresh tokens for the client. Cancel leaves them active. Reconnecting requires new approval. Revocation doesn't delete projects or undo changes already made.

Manual bearer tokens are managed under API tokens on the same page. They aren't revoked by disconnecting an unrelated OAuth client.

Common failures

For a symptom-by-symptom procedure, see Fix your AI assistant's connection to RightMessage.