MCP server

The Voidhash MCP server connects an AI agent to your project. A compatible agent can read revenue, subscription and trial analytics and ad campaign performance, and inspect and edit paywalls, write components, and render previews. This page shows how to create credentials, point your client at the server, and confirm that it works.

Server

The server runs at one URL:

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

It uses streamable HTTP as its transport and bearer authentication, so the client sends a key in the Authorization header on every request.

The server 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. A request lists, and can call, only the tools its credential has permission for, so the same server serves a read-only reporting agent and a paywall designer.

Tools that only read are marked with MCP's read-only annotation, so clients can run them without asking for confirmation.

Analytics

list_insights returns the built-in insights, such as revenue, MRR, active subscriptions, trials, trial conversions and churn, with what each measures, its unit, and the time ranges, granularities and filters it accepts. run_insight runs one insight with the same inputs as the insights endpoint: a time range preset such as last_30d or a custom start and end, a granularity, and an optional filter. It returns the period it covered, a summary, and one value per bucket, with the unit:

{
  "insightId": "builtin/revenue",
  "unit": "USD",
  "environment": "production",
  "period": {
    "start": "2026-10-01T00:00:00.000Z",
    "end": "2026-10-08T00:00:00.000Z",
    "granularity": "day"
  },
  "summary": { "value": 1250.4, "meaning": "total over the period" },
  "series": [{ "start": "2026-10-01T00:00:00.000Z", "value": 180.25 }]
}

Amounts are in US dollars and net of refunds, rates are percentages, and periods are in UTC. run_insight reports production purchases only, unlike the insights endpoint. To include sandbox purchases, filter on provider.environment yourself (1 is production, 2 sandbox); the result's environment field shows whether the production default applied.

acquisition_report takes the same inputs as the acquisition endpoint: a from and to day, the level to group by (network, campaign, adset or ad), and optionally a network, currency, time zone, revenue window and environment. Each group reports the people its first touch acquired, their trials, trial conversions, payers and revenue, with the ad platform's campaign, ad set and ad IDs, so an agent can join them to the spend it reads from the ad platform. Amounts are in the requested currency. returningPeople were reached by a touch but were already known, so they are not counted as acquired. Revenue comes from production unless you set environment.

Ads

When the project has a connected Meta ad account, list_ad_campaigns lists its synced campaigns with their status, effective status, objective and budget, and each ad account's currency, time zone and sync status. Pass activeOnly to keep the campaigns that are delivering.

campaign_performance takes the same inputs as the campaign performance endpoint: a from and to day and a level (campaign, adset or ad), and optionally an ad account, currency, time zone, revenue window and environment. Each row joins Meta's spend, impressions, clicks and reported conversions with the people Voidhash attributes to the campaign, ad set or ad, their trials and payments, and the costs and returns computed from them. Money is in the ad account's currency and days in its time zone unless you ask otherwise. Read the warnings before acting on the numbers: they flag a sync that failed or a time zone that differs.

Create credentials

For a single project, use a secret key of the project and keep it out of source control. An agent that only reports on your business needs no more than a key with Read-only analytics access, which sees only the analytics and ads tools; see Limit what a secret key can do. Send the key as a bearer token:

Authorization: Bearer vh_sk_...

A user key can access several projects, so the server also needs to know which one you mean. Send the project ID or slug in a second header:

Authorization: Bearer vh_...
X-Voidhash-Project: my-project

The CLI can print these headers for the current login. This keeps the key out of a command argument:

npx voidhash-cli auth token --project my-project

Configure your client

In your MCP client, add a remote or streamable HTTP server named voidhash, then set the URL and headers from above. Clients that use JSON configuration commonly accept this shape:

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

Configuration keys differ between clients. Some expect servers instead of mcpServers, or serverUrl instead of url. In those cases, follow your client's own remote MCP instructions.

Verify the connection

Ask the agent a question that needs the server:

What paywalls do I have in Voidhash?

The agent should call list_paywalls and return the current project's paywalls. With a read-only analytics key, ask for a metric instead, such as "What was my revenue over the last 30 days?", and the agent should call run_insight. If it receives a 401, replace the key. If a user key authenticates but no project is selected, add the X-Voidhash-Project header. If a tool you expect is missing, the credential lacks its permission.