Potarix MCP Server

MCP wrapper for Potarix Enricher. Lets AI agents resolve company websites, find verified emails, and pull complete company rosters — and (with one human-in-the-loop card capture) sign up and pay for credits entirely from the agent.

Tools

tool	what it does	cost
`lookup_company_website`	company name → website URL	2 credits
`find_person_email`	named person + company/domain → verified email	25 credits
`find_decision_maker_email`	category + domain → likely buyer name + email	25 credits
`find_linkedin_email`	LinkedIn profile URL → verified email	10 credits
`find_company_emails`	domain → public company contact roster	25 credits
`find_all`	one company name → website + DMs + full company email list	sum of above
`check_balance`	credits, email, saved-card status, key count	free
`start_checkout`	get a Stripe URL to add a card the first time	n/a
`topup_credits`	charge the saved card and add credits	n/a

1 credit = $0.01. Trial accounts start with 25 free credits. Every endpoint floors at the worst-case provider COGS — a hit never loses money, and short-circuited waterfall calls earn margin.

Two ways to connect

transport	endpoint	best for
Streamable HTTP (hosted)	`https://api.potarix.com/mcp`	remote agents (Claude, ChatGPT) — no install
stdio (npm package)	`npx -y potarix-mcp`	local/desktop clients

Both expose the same nine tools. The hosted server is stateless and multi-tenant: every request is authorized by its own Authorization: Bearer ptk_live_... header, so there is no per-user deployment.

Hosted (Streamable HTTP)

Point any MCP client that speaks Streamable HTTP at https://api.potarix.com/mcp and send your key as a bearer token:

JSON Config

{
  "mcpServers": {
    "potarix": {
      "url": "https://api.potarix.com/mcp",
      "headers": { "Authorization": "Bearer ptk_live_your_key" }
    }
  }
}

Install (stdio)

Terminal

npm install -g potarix-mcp

Or run it without a global install:

Terminal

npx -y potarix-mcp

Configure

Set your Potarix API key:

server.ts

export POTARIX_API_KEY=ptk_live_your_key

Optional:

server.ts

export POTARIX_API=https://api.potarix.com/enricher

Claude Desktop

config.json

{
  "mcpServers": {
    "potarix": {
      "command": "npx",
      "args": ["-y", "potarix-mcp"],
      "env": {
        "POTARIX_API_KEY": "ptk_live_your_key"
      }
    }
  }
}

Claude Code

Terminal

claude mcp add potarix npx -- -y potarix-mcp

Then add POTARIX_API_KEY to the environment where Claude Code runs.

Development

Terminal

npm install
npm run build
npm run smoke        # stdio transport: connect + tools/list

# Streamable HTTP transport:
npm run start:http   # serves on http://127.0.0.1:8080/mcp (set PORT to change)
# in another shell:
POTARIX_MCP_URL=http://127.0.0.1:8080/mcp npm run smoke:http

Environment variables:

var	default	purpose
`POTARIX_API_KEY`	—	API key (stdio only; HTTP reads it per-request from the bearer header)
`POTARIX_MCP_TRANSPORT`	`stdio`	`http` to run the Streamable HTTP server (or pass `--http`)
`PORT` / `HOST`	`8080` / `127.0.0.1`	HTTP bind address
`POTARIX_MCP_PATH`	`/mcp`	HTTP request path
`POTARIX_MCP_ALLOWED_HOSTS`	—	comma-separated host allow-list; enables DNS-rebinding protection
`POTARIX_API`	`https://api.potarix.com/enricher`	API base URL override

Registry Publishing

This repo includes server.json for the official MCP Registry. The entry is multi-surface: it declares both the hosted Streamable HTTP remote (https://api.potarix.com/mcp) and the npm stdio package (potarix-mcp), so a single registry record advertises two ways to connect.

The registry validates the npm package by fetching it and checking that its published mcpName matches the server name, so the npm package must be published first, at the same version named in server.json (packages[].version).

Publishing steps (version-bump first, then npm, then registry):

bash

# 1. Bump package.json + server.json to the same new version (e.g. 0.1.3).
#    server.json must be a NEW version each publish (versions are immutable).
# 2. Build + publish the npm artifact (carries mcpName for ownership proof):
npm publish
# 3. Push the multi-surface server.json to the official MCP Registry:
mcp-publisher login github
mcp-publisher publish

The package mcpName in package.json must match server.json:

text

io.github.Potarix/potarix-mcp