MCP server

The Voidhash MCP server connects an AI agent to Voidhash. A compatible agent can answer support questions about your end users, manage products, perks and store mappings, design, deploy and A/B test paywalls, run feature flags, read revenue, acquisition and ad performance, debug webhooks, and manage your team and settings. Changes that cannot be undone wait for your agreement, and a few things, such as store credentials and API keys, stay with you. This page shows how to add the server to your agent, how it signs in, which tools it offers, and how to confirm that it works.

Connect your agent

Add the server to your agent. It signs in through your browser the first time it uses Voidhash, so there is no key to copy or store.

To set up every agent on your computer at once, run:

npx voidhash-cli mcp install

It finds Claude Code, Cursor, Codex, VS Code and Claude Desktop and adds the server to each one you choose. It writes no keys.

Other agents need a remote MCP server that uses streamable HTTP and supports MCP sign-in (OAuth). Clients that use JSON configuration commonly accept this shape:

{
  "mcpServers": {
    "voidhash": {
      "type": "http",
      "url": "https://api.voidhash.com/api/mcp"
    }
  }
}

Your agent acts as you

When the agent first calls the server, your browser opens and you sign in to Voidhash. From then on the agent acts as you: it can do what your role allows in each project of each organization you belong to, and nothing more. When your role changes, or you leave an organization, the agent's access changes on its next request.

Agents you sign in are listed under Settings → Connected apps in Studio, with the CLI. From there you can:

• make an agent read-only, so it can read but every change is refused;
• disconnect an agent, which then needs to sign in again.

A newly connected agent can do everything your role allows; make it read-only from Connected apps right after it first appears there. Each agent keeps its setting when it signs in again, and an agent that goes unused for 90 days is signed out. An agent can never change its own setting, disconnect other apps, or create keys; only you can, signed in to Studio.

Every change an agent makes is recorded in the audit log as yours, with the agent named beside you.

Server

The server runs at one URL:

https://api.voidhash.com/api/mcp

It uses streamable HTTP as its transport. It implements the stateless MCP protocol, version 2026-07-28. Each request stands on its own, with no initialization handshake or session to keep alive. Clients that support only the earlier session-based versions cannot connect.

Tools

The server groups its tools into toolsets, one for each part of Voidhash. Each tool does one task and combines the reads it needs: get_person, for example, returns a person's profile, access, subscriptions, purchases and recent events in one call.

A request lists, and can call, only the tools you (or the secret key) have permission for, so the same server serves a read-only reporting agent and a paywall designer. A read-only agent sees only the tools that read. Tools that read carry MCP's read-only annotation, so clients can run them without asking you; tools that delete or overwrite something are marked destructive.

Choosing a project

Every project tool takes an optional project argument, a project ID or slug. list_projects lists the projects you can use, with their organizations. You can leave project out when you have only one project, when the agent uses a secret key (which belongs to one project), or when the client sends a default project in the X-Voidhash-Project header. Otherwise the tool asks for one.

Team tools (list_members, invite_member, change_member_role, remove_member, create_project, list_notices and send_feedback) take an optional organization instead: its ID, slug or name. They default to the organization of your default project.

Names instead of IDs

Tools take things the way people name them: a product, perk, paywall or location by its ID, slug or exact name; an end user by email, distinct ID or person ID; a webhook by its ID, name or URL; a flag by its key. When a name fits several things, the tool lists them with their IDs instead of guessing.

Results start with a short summary in words, with money and dates written as people read them and the IDs a follow-up call needs, followed by the same result as structured data. Long lists come a page at a time. When a call fails, the error says what was wrong and which tool or argument fixes it.

Changes that ask first

A change that cannot be undone, or that reaches many end users at once, does not happen on the first call. The tool reports what would change and who it affects, changes nothing, and returns the exact arguments that make the change, with confirm: true. Your agent should show you the report and call again only once you agree. The confirmed call acts on the IDs you were shown, so a name that starts to mean something else in between cannot redirect it.

These tools ask first, always or in the cases listed:

What stays with you

Some things an agent cannot do, whatever your role. You do them yourself, signed in to Studio or with the CLI:

• Store credentials. Connecting the App Store, Google Play or Stripe, changing their keys and removing a store. Agents see whether each store works and map its products.
• Push credentials. Setting up APNs and FCM. Agents send push notifications through them.
• Ad accounts. Connecting a Meta ad account, which needs its access token. Agents read the synced campaigns and can disconnect an account.
• API keys. Creating, rotating, rescoping and deleting keys. list_api_keys only reads them.
• Connected apps. Making an agent read-only or disconnecting it, including the agent itself.
• Accepting the Terms, and installing registry components and uploading fonts for paywalls.

Signing secrets are the exception that passes through an agent: create_webhook, rotate_webhook_secret, create_payment_source and update_payment_source return a new secret once. Your agent should hand it straight to your backend's secret configuration, not to a chat or a file in your repository.

Toolsets

The toolsets below are listed in the order agents see them. The permission column names what a role or secret key needs for each tool.

Orientation

Where an agent starts in a project.

Each finding of get_project_status says what to do and which tool does it, or that you have to.

Persons

The end users of your app: what they bought, what they can use, and data erasure requests. Persons are found by exact email, distinct ID or person ID; names and parts of an email cannot be searched.

Subscriptions, purchases and access are shown for production store purchases. See Data deletion for what erasure removes and keeps.

Catalog

What end users buy and what it unlocks: a product grants perks, and your app checks access by perk slug. See Products and perks.

A new product grants nothing until it has perks, and cannot be bought until it is mapped to a store product (map_store_product).

Payment providers

Where your project takes payments: the App Store, Google Play, Stripe, and payment sources that report their own purchases. Providers are named by store (app_store, google_play, stripe), by bundle ID, package name, Stripe account or payment source slug, or by name. Stripe store products are prices, written prod_…:price_…; Google Play base plans productId:basePlanId.

Imports and recorded payments take an environment, production or test: test reads Stripe's test mode or a payment source's test payments, which stay out of production revenue. A source's test endpoint answers its test requests; without one they go to its endpoint.

Paywalls

What end users see where. A paywall's deployed build is shown at the paywall locations that show it, which your app asks for by slug. See Paywall locations.

Only a person can start a build. An agent with a secret key can deploy a build that already exists.

Paywall design

Designing paywalls and writing code components. Design changes are made in an edit session, which you and others see live in the paywall editor; end users see them only once deploy_paywall deploys the design.

The toolset also serves the authoring guides as resources, voidhash://skills/paywall-authoring and voidhash://skills/code-component-authoring, and a design_paywall prompt that starts a design workflow for one paywall.

Feature flags

Whether a feature is on for each end user, and which variant they get. A flag that is off is off for everyone. When it is on, an override fixes it for one end user, the deny and allow lists limit who can get it, and the rollout percentage decides the rest.

Experiments

A/B tests of paywalls: each arm shows a paywall at one or more paywall locations. What counts as a conversion is fixed once an experiment starts, and its arms cannot change while it runs.

Analytics

Revenue and subscription metrics, acquisition by first touch, and the events your apps send. Periods are said in words: "last 30 days" (the 30 complete days before today), "this month", "last month", "ytd", "2026-09" or "2026-09-01..2026-09-30". See Ad measurement for how first touches are counted.

run_insight reports production purchases unless you ask for another environment, and takes insights by the names people use ("MRR", "churn rate").

Ads

Paid acquisition from your connected Meta ad accounts: what each campaign spent beside the signups, payers and revenue Voidhash measured. The platform's numbers and Voidhash's are reported apart and never added together. Voidhash reads ads and never changes them.

Voidhash's numbers in the ads reports also need project:analytics:read. Connecting an ad account stays with you; see What stays with you.

Webhooks

Your project's purchase, subscription and person events, sent to your backend, and why it misses some.

Your backend receives a retried event again, so it should handle an event it already processed.

Messaging

Push notifications to your end users' devices, through the APNs and FCM credentials you set up in Studio under Settings → Notifications.

Team and settings

Who belongs to an organization, new projects, a project's settings explained, tracking domains, keys and the audit log.

Sandbox

Testing your app's purchase flow without a real store. A debug build of your app buys through the Voidhash sandbox; these tools show those purchases and play the store's later events.

Production purchases and store sandbox purchases, such as TestFlight and Play test tracks, are never changed. Turn sandbox purchasing on or off with update_project_settings.

Example prompts

Agents combine the tools on their own. A few requests and the tools they lead to:

Someone says they paid for Pro but have no access. Their email is ada@example.com.

find_persons finds the person and explain_person_access traces their access to the perk. If a store product is not mapped, list_store_products and map_store_product fix it, after you confirm moving a mapping.

Add a yearly plan that grants premium and show it in the onboarding paywall.

create_product adds the product and set_product_perks grants premium. Once you have mapped it to its store products, begin_paywall_edit, edit_paywall and get_paywall_preview add it to the design, finish_paywall_edit ends the session, and deploy_paywall makes it live after you agree.

Test whether showing the annual plan first raises trial starts at onboarding-end.

create_experiment sets up the arms, start_experiment reports the locations and split and starts once you agree, and later get_experiment_results and conclude_experiment pick the winner.

Our backend missed purchase events last night. Find out why and resend them once it is fixed.

list_webhook_failures shows how your endpoint answered, test_webhook checks it after the fix, and retry_webhook_delivery sends what gave up.

Which Meta campaigns paid back last month, and is anything broken?

list_ad_accounts checks that syncs are current, ads_performance_report compares spend with the revenue Voidhash measured, and find_ads_issues lists what needs attention.

Verify the connection

Ask the agent a question that needs the server:

Which Voidhash projects can you see?

The agent should call list_projects. Then ask about one of them, such as "What was my revenue over the last 30 days in my-project?", and the agent should call run_insight.

If the agent reports that it is not signed in, start its sign-in again; in Codex, run codex mcp login voidhash. If a tool you expect is missing, your role does not allow it in that project, or the agent is read-only.