Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Connect an AI agent to your Mesub organization with MCP

What it is

An MCP server that Mesub hosts. Your AI tool connects to it, and its agent can then read the projects of one organization and act on them, the way you would in the dashboard. There is nothing to install and no API key to hand over.
It is not the agent skills. The skills teach an agent to write your integration, in your codebase. The MCP server lets an agent act on your projects: look at a subscription, retry a charge, add a webhook.
The agent acts with your role in the organization, read again on every call. It can use every tool your role allows, and no other. There is no read-only mode, so connect an agent only if you would let it do all of that.

Connect

  1. Add the server's address to your AI tool, as a remote MCP server.
  2. The tool opens a Mesub page in your browser. Sign in to the dashboard.
  3. Under Connect to, find the organization. Choose Whole organization, or pin the agent to one project under Or only one project.
  4. Read what the page lists, then press Authorize.
The address:
https://mcp.mesub.io/mcp
It is the production server: it reaches the organizations and projects of mesub.io.
A tool configured by a JSON file takes an entry like this one:
{ "mcpServers": { "mesub": { "url": "https://mcp.mesub.io/mcp" } } }
Some tools want "type": "http" beside the url. A tool configured from a terminal takes the same two things, a name and the address. The words of the command are your tool's own, this is only its usual shape:
your-tool mcp add --transport http \ mesub https://mcp.mesub.io/mcp
Nothing is chosen for you, with one exception. If you pressed Connect agent inside a project of the dashboard, in this browser in the last 15 minutes, that project is chosen as the pin, if it still has room. You can change it before you authorize.
Once you choose, the page says what the agent will reach, and with which role. For an organization called Northwind, with the projects Shop and Docs:
  • Whole organization: "All current and future projects of “Northwind”." A project you create later is reached too.
  • Pinned to Shop: "Only the project “Shop”." The agent never reaches Docs.
The page that asks you to authorize shows the name the application gave itself. Beside it is the host that publishes the application when Mesub could check one, and Unverified app when it could not. The page also says where your browser is sent back to: check both before you authorize. A request you leave open is dropped after ten minutes.
A connection reaches one organization. To work on another organization, or on another project than the pin, connect again and choose it.

What the agent can do

Read
ToolWhat it does
list_projectsThe projects the connection reaches, with their id, name and tier, and your role and what it allows
get_projectOne project, its tier, and how much of its limits is used
list_plansEvery plan, with its subscribers and what it collected this period. A plan waiting in To sign is listed there with its link
get_planOne plan: its subscribers by status, its latest charges, why charges fail
list_subscriptionsSubscriptions, by plan or by status, or found by wallet or by your own customer id
get_subscriptionOne subscription and every charge tried on it
check_accessWhether a customer has access, and why not when they do not
list_eventsWhat happened on a day, over the last 45 days: payments, subscribers, changes to the project. Finds a charge by wallet, your customer id or the start of its signature
list_upcoming_chargesThe charges and retries to come, each one Mesub already expects to fail flagged with why
get_overviewCollected, failed and recovered over 7, 30 or 90 days
list_webhooksThe webhook endpoints, never their secret
list_webhook_deliveriesAn endpoint's deliveries and what your server answered
get_webhook_secretAn endpoint's signing secret
search_docsSearch these docs. It reads nothing of your projects
pingWhether Mesub answers
Act
ToolWhat it does
retry_chargeRetry a failed charge, when a customer is late. Mesub refuses one that cannot succeed or a wallet short of funds, spending no retry
update_retry_policyChange how many times a plan retries, and how far apart
create_webhookAdd an endpoint and return its signing secret
update_webhookChange the URL or the events of an endpoint, turn it off or back on
delete_webhookDelete an endpoint
regenerate_webhook_secretDraw a new signing secret. The old one keeps signing for overlap_hours, 0 to 24: at once by default
send_test_webhookSend a test delivery to an endpoint
update_projectRename a project
Prepare
ToolWhat it does
prepare_planFill in a plan for you. It does not exist until the organization wallet signs it
Before preparing, your agent asks you two things: whether to lock the receiving wallets (up to four, and which one is paid for now) and whether the plan has an end, a day and a time in UTC. A locked list can never change once the plan is signed. With no list, the plan pays into the organization wallet, and the Owner or an Admin can change the receiving wallet later in the dashboard.
Who signs a plan the agent prepared. Whoever holds the organization wallet. The plan waits in To sign. The agent hands you the plan's page, where you review it and can still edit it, and usually its entry in To sign too. The organization wallet signs from either one. In a personal organization, the organization wallet is the wallet your Mesub account signs with, until you register another one in Organization settings.
The tools describe their own parameters to the agent, so there is nothing to learn here: ask in plain words.

Which project a tool works on

Every tool but list_projects, search_docs and ping takes a project: the project's id, or its name. The agent does not need to know the ids or names in advance: list_projects returns every project the connection reaches. The agent calls it when it does not know which project you mean.
When the agent leaves project out, the tool falls back like this:
ToolsWith project left out
list_plans, get_plan, list_subscriptions, get_subscription, list_events, list_upcoming_charges, get_overviewEvery project the connection reaches
get_project, check_access, list_webhooks, list_webhook_deliveries, get_webhook_secretThe pinned project, or the organization's only project. Else it is refused
Every tool that changes something, prepare_plan includedThe pinned project. Else it is refused, even in an organization of one project
So on Northwind, connected as a whole:
  • "Which payments failed this week?" reads Shop and Docs together. Each event says which project it belongs to.
  • "Add a webhook for failed payments" needs a project. The agent asks you which one, then calls create_webhook with project: "Shop".
  • On a connection pinned to Shop, the same request needs no project: it lands in Shop. Naming Docs there is refused.
A name is matched inside the organization only. An exact name match comes first. If there is none, case is ignored: shop finds Shop. When the value names two projects, the agent uses the id instead. A project of another organization is never found, even one you are a member of.
Every change names the project it acted on, for example "Project acted on: “Shop”." The MCP server compares it with the project the agent named. When they differ, the server returns project_mismatch, and the agent stops and tells you. Mesub's answer to delete_webhook does not name a project, so the agent cannot confirm where the endpoint was deleted.

What each role's agent can do

The agent has the rights your role has in the dashboard, checked live on every call. The Owner's and Admins' agents can use every tool. A Member's agent can use every tool except these:
ToolWhat a Member's agent is told
get_webhook_secret"Only the Owner and Admins can read webhook signing secrets."
create_webhook, update_webhook, delete_webhook, regenerate_webhook_secret, send_test_webhook"Only the Owner and Admins can manage webhooks."
update_project"Only the Owner and Admins can rename this project."
A Member's agent still reads every project, checks access, retries charges, changes a plan's retry policy and prepares plans.
The role is read on each call, never kept in the connection. An Admin demoted to Member: their agent's next webhook call is refused. Someone removed from the organization: their agents are disconnected.

When a call is refused

A refused call returns a Mesub error code, its message and what to do next. The server tells the agent never to call a tool that changes something again after it failed, unless the error says it is temporary.
CodeWhenWhat happens next
role_requiredYour role does not allow the toolThe agent relays the message as it is and does not retry. The Owner or an Admin can do it for you, or the Owner can make you an Admin. Connecting again changes nothing
team_wallet_requiredprepare_plan in an organization, not a personal one, with no organization walletNothing is prepared. The agent gives you a link to Organization settings, where the Owner sets the organization wallet. Then the agent calls again
wallet_requiredprepare_plan in a personal organization whose Owner has connected no walletNothing is prepared. In your own organization, the agent gives you the link where you connect your wallet. In someone else's, the message names its Owner, who connects one. Then the agent calls again
period_too_shortprepare_plan with a period under a day, on Free or DevNothing is prepared. The agent asks you for a period of a day or more, or to move the project to Business in the dashboard
project_requiredNo project, where the table above refuses itThe agent calls list_projects, asks you which project when it is not clear, then calls again with it
project_not_foundNo project of the organization has that id or nameThe agent takes the project from list_projects
project_ambiguousThe value names two projects, for example one's id and another's nameThe agent calls again with the id
project_outside_pinA pinned connection named another projectYou connect again and choose the whole organization, or that project
project_mismatchMesub's answer names another project than the one the agent named, or names noneThe agent tells you and stops. The change may have gone through elsewhere: check it in the dashboard
For example, a pinned connection that names Docs gets: "This connection reaches “Shop” only. Connect again without a pin to work on another project."

What it can never do

Whatever the agent is asked, by you or by anything it reads:
  • Do more than your role allows.
  • Reach a project of another organization, or another project than its pin.
  • See or change your API key.
  • Change a project's tier.
  • Delete a project or a plan.
  • Close a plan, or change the end or the receiving wallets of a plan already signed.
  • Sign a plan. It prepares one; the organization wallet signs it.
  • Resend an old webhook delivery.
  • Read a customer's email. It can check access for an email you give it, and never gets one back: a customer is shown by wallet and by your own id.
  • Cancel or change a customer's subscription. Only their wallet can.
These are not tools switched off: the server has no such tool, and Mesub gives an agent no way to them.

Limits

Per connection: 120 reads and 20 changes a minute, and 5 test deliveries a minute, refused ones included. A connection to a whole organization has one budget for all its projects.
How many agents can be connected at once:
  • 10 per organization, for connections to the whole organization.
  • 10 per project pinned to it. A connection to the whole organization takes none of these places.
  • 30 per Mesub account, across everything you connected.
Only live connections count: one revoked, or unused for a day, frees its place. When there is no room, the consent page greys out that choice, and Mesub refuses the approval with agent_connection_cap_reached. Revoke a connection first.

See and cut a connection

In the dashboard, AI & agents lists every agent connected to the organization, whole or pinned, and is where you revoke one. Inside a project, Developers, then Agents, only lists the agents that reach that project: those pinned to it, and those connected to the whole organization. Its Manage in AI & agents button leads to the organization's list. Each line is one connection: the application, what it reaches, when it connected, when it was last used and when it ends.
The Owner and Admins see everyone's agents. A Member sees their own.
  • Revoke, in AI & agents, cuts a connection. The agent's very next call is refused. A connection to the whole organization is cut from every project at once.
  • You can always revoke your own. The Owner and Admins can revoke a Member's agent. Only the Owner can revoke an Admin's agent or the Owner's own.
  • A connection ends by itself after a day without use. While it is used, it stays open: your tool renews its one hour token by itself.
Cutting a connection undoes nothing: what the agent changed stays as it is. To connect again, start from your tool.

Risks

A signing secret lands in your conversation. When an agent creates a webhook, regenerates its secret or reads it, the secret is in the answer, so it is in the conversation and wherever your tool keeps it. Move it to your server's environment, and regenerate it if the conversation is shared.
What the agent reads is written by other people. A plan's name, a project's name, what a webhook endpoint answered, the identifier of a customer: all of it is text somebody else chose, and it can be written to look like an instruction. The server tells every agent to treat it as data. An agent can still be steered by it. That is why the tools that move money or break an integration, such as retrying a charge, deleting a webhook or regenerating its secret, are marked so that your tool asks you first. Keep that question on, and read it.
A connection to the whole organization reaches more. It reaches every project, those created later included. Pin the agent to one project when it needs only that one.
You review every plan waiting in To sign. The agent fills it in, the organization wallet signs it. Read the project, the price, the token, the period, the end and above all the receiving wallets in the dashboard before signing: each one is shown in full and marked when it is not on your Mesub account. You can still edit the plan there first.

Things to ask

  • "Which projects can you see?"
  • "Why does this customer have no access in Shop?"
  • "Which renewals are at risk this week, across all projects?"
  • "Add a webhook for failed payments to Docs and give me the secret for my .env"
  • "Prepare a Pro plan at 10 USDC a month in Shop"
For what the answers mean, see the lifecycle and check access.