This article walks you through connecting a headless server (no browser, no interactive user session) to the PMA MCP server using a static Bearer token. It is intended for developers integrating the MCP server into custom backend services such as Node.js APIs, scheduled jobs, or agentic systems running on infrastructure like Fly.io, Render, AWS, or your own data center. For a full overview of the PMA MCP server, including the available tools and worked examples, see the Power My Analytics MCP Server Guide.

The PMA MCP server is currently in Alpha. Access is granted per organization on request. To request access, open a support ticket with the subject line "MCP Early Access" at support.powermyanalytics.com.

How Headless Auth Differs from the Browser Flow

The PMA MCP server supports two equivalent authentication paths:

• Browser-based clients (Claude Desktop, Claude Web, Claude Code, ChatGPT) complete an OAuth 2.1 + PKCE handshake and receive an access token that is valid for 1 year.
• Headless / server-to-server clients skip OAuth entirely and authenticate directly with their PMA API token as a Bearer credential.

Both paths ultimately resolve to the same underlying API token; OAuth is provided to satisfy the browser-based connector flow used by Claude.ai, ChatGPT, and similar tools. For a custom backend service, the API-token path is simpler and is the supported pattern.

Requirements

Before you begin, confirm the following on both sides of the connection.

On your server:

• An MCP client library that supports the Streamable HTTP transport with a custom Authorization header. The official @modelcontextprotocol/sdk package ships with a compatible StreamableHTTPClientTransport; equivalent libraries exist in other languages.
• The ability to set environment variables or use a secrets store; never hard-code the token in your source.
• Outbound HTTPS connectivity to https://pma-mcp.web.app.

On the Power My Analytics side:

• Your PMA organization must be allow-listed for MCP Alpha access by the PMA team.
• Org Admin role in PMA.
• At least one data source connected and actively syncing in your PMA Hub.
• A PMA API token associated with your organization. This token is provisioned by the Power My Analytics team during your alpha onboarding; you do not need to generate one yourself. If you need to rotate it, see Token Rotation below.

Step 1: Retrieve Your PMA API Token

Your PMA API token is the same token used to authenticate any server-side request to PMA, and it is the credential the MCP server expects in headless mode.

1. Locate the API token shared with you during your MCP Alpha onboarding (typically delivered via your alpha access support ticket).
2. Store it in your service's secrets manager or environment-variable system (for example, PMA_API_TOKEN in Fly.io secrets, AWS Secrets Manager, GitHub Actions secrets, or equivalent).
3. If you cannot locate the token, contact PMA support; do not assume an old token has been invalidated, since previously-issued tokens remain valid until they are rotated.

Treat the API token like any production credential. It is scoped to your organization and grants the same data-access scope an Org Admin has in the Hub. Do not commit it to source control, share it in chat, or expose it in client-side code.

Step 2: Configure Your MCP Client

Point your MCP client at the PMA MCP endpoint and pass your API token in the Authorization header:

• Endpoint: https://pma-mcp.web.app/mcp
• Transport: Streamable HTTP
• Header: Authorization: Bearer <your-pma-api-token>

Node.js Example (@modelcontextprotocol/sdk)

The example below uses the official Model Context Protocol SDK for TypeScript and JavaScript. It connects to the PMA MCP server, lists the available tools, and calls pma_list_data_sources as a sanity check.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const PMA_API_TOKEN = process.env.PMA_API_TOKEN;
if (!PMA_API_TOKEN) {
  throw new Error("PMA_API_TOKEN is not set in the environment.");
}

const transport = new StreamableHTTPClientTransport(
  new URL("https://pma-mcp.web.app/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${PMA_API_TOKEN}`,
      },
    },
  }
);

const client = new Client(
  { name: "my-pma-headless-service", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

// List tools (sanity check)
const { tools } = await client.listTools();
console.log("Available PMA MCP tools:", tools.map((t) => t.name));

// Call a tool
const sources = await client.callTool({
  name: "pma_list_data_sources",
  arguments: {},
});
console.log(sources);

await client.close();

Other Languages and Clients

Any MCP client library that supports Streamable HTTP transport plus a static Bearer token will work. The general requirements are:

1. Set the request URL to https://pma-mcp.web.app/mcp.
2. Use Streamable HTTP transport (not the older Server-Sent Events transport from earlier MCP versions).
3. Send Authorization: Bearer <token> on every request.

For background on the Streamable HTTP transport itself, see the Model Context Protocol specification.

Step 3: Verify the Connection

Once connected, run a low-cost diagnostic call to confirm everything is wired up correctly. We recommend pma_list_data_sources for the first verification: it returns the same list you would see under Sources in your Hub, including each platform's has_data flag and last_sync timestamp. If the call succeeds and returns the expected platforms, your headless integration is working.

For a complete tools inventory, see the PMA MCP Tools Reference.

Token Rotation

PMA API tokens issued for MCP alpha access are long-lived: they do not expire on their own. You should rotate the token whenever you would rotate any other production secret, including:

• Suspected compromise or accidental exposure.
• An employee with access to the token leaving the organization.
• Periodic rotation per your security policy.

To rotate your PMA API token, follow How to Generate a New API Key. After rotating, update the token value wherever it is stored (secrets manager, environment variables, deployment configuration) and restart your service so the new token takes effect.

Refresh tokens are not implemented for the PMA MCP server's OAuth path. This does not affect headless integrations, because the static API token used in this article does not expire on its own. If you are using the OAuth flow from Claude Desktop, Claude Web, Claude Code, or ChatGPT, see Connect to the PMA MCP Server from Claude Desktop for browser-based reconnect steps.

Troubleshooting

Connection rejected with 401 or "unauthorized"

Cause: The Authorization header is missing or malformed, or the token is invalid or has been rotated. Solution: Confirm that the header is exactly Authorization: Bearer <token> (the literal word Bearer, a single space, then the token). Confirm the token value in your secrets manager matches the most recent token PMA issued. If the token was rotated, replace the old value and restart your service.

Connection rejected with 403 or "organization not authorized"

Cause: Your PMA organization is not yet on the Alpha access list, or alpha access has been deactivated. Solution: Open a support ticket with the subject line "MCP Early Access" at support.powermyanalytics.com to confirm or restore your access.

Tool calls return "rate limit exceeded" or HTTP 429

Cause: The MCP server enforces a hard limit of 30 requests per minute per organization. Agentic loops, fan-out queries across many platforms, or aggressive retries can hit this limit. Solution: Slow your call cadence, batch requests where possible, and add exponential backoff to your retry logic. For more on this and other limitations, see Troubleshooting and Important Considerations for PMA MCP Server.

A tool returns no rows for a platform you know is connected

Cause: Either the initial sync has not completed for that platform, the wrong report type is being queried, or the connector name passed to the tool does not exactly match a connected source. Solution: Call pma_list_data_sources first to confirm canonical connector names and has_data status, then retry. Use pma_inspect_org_data for a deeper diagnostic if a specific connector still returns nothing.

MCP client cannot establish a Streamable HTTP connection

Cause: Your client library may default to the older Server-Sent Events transport, or your network may be closing long-lived HTTP responses. Solution: Confirm your MCP client is using Streamable HTTP transport explicitly. If you are running behind a proxy or a restrictive firewall, allow https://pma-mcp.web.app and confirm long-running responses are not being closed prematurely.

Related Articles

• Power My Analytics MCP Server Guide
• PMA MCP Tools Reference
• Connect to the PMA MCP Server from Claude Desktop
• Connect to the PMA MCP Server from Claude Code
• Connect to the PMA MCP Server from ChatGPT
• Troubleshooting and Important Considerations for PMA MCP Server
• How to Generate a New API Key