# HyPeMa - MCP Integration Guide
> Connect HyPeMa to Claude, ChatGPT, Cursor, and any AI platform that supports MCP.

---

## Table of Contents

- [Overview](#overview)
- [Claude.ai (Web & Mobile)](#claudeai-web--mobile)
- [Claude Desktop](#claude-desktop)
- [Claude Code (CLI)](#claude-code-cli)
- [ChatGPT](#chatgpt)
- [Cursor / VS Code / GitHub Copilot](#cursor--vs-code--github-copilot)
- [Other Platforms](#other-platforms)
- [Tools Reference](#tools-reference)
- [Troubleshooting](#troubleshooting)

---

## Overview

HyPeMa has a remote **MCP server** (Model Context Protocol) that lets any compatible AI assistant use HyPeMa directly. Instead of switching to the web app, you can research companies, find leads, and draft emails from inside your AI chat.

### One server, every platform

The same MCP endpoint works with Claude.ai, Claude Desktop, ChatGPT, Cursor, VS Code, and 10+ other AI platforms. Set it up once and your AI assistant gets access to all 15 HyPeMa tools.

### Architecture

```
AI Assistant  -->  MCP Server  -->  HyPeMa API
(Claude / ChatGPT / Cursor)    MCP protocol    (mcp.hypema.app)    REST API    (REST + AI Services)
```

### Two ways to authenticate

| Method | Best for | Details |
|--------|----------|---------|
| **OAuth (recommended)** | Claude.ai, ChatGPT, Claude Desktop | Sign in with your HyPeMa or Google account. Auto-configured during setup. |
| **API Key** | Cursor, VS Code, CLI tools | Generate a key at Settings -> API Keys and add it to your config file. |

### Server URL

```
https://mcp.hypema.app/mcp
```

### Pick your client

Jump to the setup that matches how you use AI today.

| Category | Clients | Auth |
|----------|---------|------|
| **AI Chat** | Claude.ai · Claude Desktop · ChatGPT | OAuth |
| **IDE / CLI** | Cursor · VS Code · Claude Code · JetBrains · Zed | API key |
| **Custom / Other** | Windsurf · OpenClaw · OpenAI Agents SDK · Cline · Goose · Gemini ADK | Mixed |

### First 5 minutes

Fastest path: install Claude Code (or use Claude Desktop's GUI connector), add HyPeMa with one command, then try the three prompts below. You'll have a real draft email sitting in your HyPeMa account in under five minutes.

```bash
claude mcp add hypema --transport http https://mcp.hypema.app/mcp
```

Prompts to try:

1. *"Research the company stripe.com"*
2. *"Find 3 heads of partnerships at fintech companies in Germany"*
3. *"Preview a cold email to the first lead about integrating our AI payments API"*

---

## Claude.ai (Web & Mobile)

The easiest way to get started. Claude.ai has built-in support for MCP connectors with OAuth -- just add the URL and sign in.

### Setup steps

1. Open **Claude.ai** and go to **Settings -> Connectors**
2. Click **"Add custom connector"**
3. Enter the URL: `https://mcp.hypema.app/mcp`
4. Claude opens the HyPeMa login page -- sign in with your HyPeMa or Google account and approve access
5. Done! HyPeMa tools now appear in your Claude conversations. Try: *"Research the company stripe.com"*

> **Note:** Free Claude users can use published connectors from the directory. Custom connectors (like adding HyPeMa by URL) require a paid Claude plan (Pro, Max, Team, or Enterprise).

---

## Claude Desktop

Claude Desktop supports MCP connectors through its GUI or via a JSON config file. You can use either OAuth (same as web) or an API key.

### Option A: Via GUI (OAuth)

1. Open Claude Desktop and go to **Settings -> Connectors**
2. Click **"Add custom connector"** and enter `https://mcp.hypema.app/mcp`
3. Sign in with your HyPeMa account when prompted

### Option B: Via config file (API Key)

Edit `claude_desktop_config.json` (Settings -> Developer -> Edit Config):

```json
{
  "mcpServers": {
    "hypema": {
      "url": "https://mcp.hypema.app/mcp",
      "headers": {
        "Authorization": "Bearer hpm_live_your_key_here"
      }
    }
  }
}
```

Get your API key at **Settings -> API Keys** in the HyPeMa web app.

---

## Claude Code (CLI)

Claude Code is Anthropic's agentic coding tool that runs in your terminal. It supports remote MCP servers natively -- just add the URL and Claude Code handles OAuth automatically.

### Via CLI (recommended)

```bash
# OAuth (opens browser on first use):
claude mcp add hypema --transport http https://mcp.hypema.app/mcp

# Or skip OAuth by passing an API key:
claude mcp add hypema \
  --transport http \
  --header "Authorization: Bearer hpm_live_your_key_here" \
  https://mcp.hypema.app/mcp
```

### Via config file

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "hypema": {
      "type": "http",
      "url": "https://mcp.hypema.app/mcp",
      "headers": {
        "Authorization": "Bearer hpm_live_your_key_here"
      }
    }
  }
}
```

### Verify connection

```bash
claude mcp list
```

You should see `hypema` listed with 15 tools. Try it out:

```bash
claude
> Research the company stripe.com and find 3 VP-level leads in partnerships
```

### Scopes

You can add HyPeMa at different scopes: `--scope user` (all projects), `--scope project` (current project only), or `--scope local` (local machine only).

---

## ChatGPT

ChatGPT supports MCP connectors via Developer Mode. OAuth is required -- API keys are not supported for ChatGPT connectors.

> **Requirement:** Developer Mode must be enabled (available on Pro, Team, Enterprise, and Edu plans). Go to Settings -> Developer Mode to enable it.

### Setup steps

1. Open **ChatGPT** and go to **Settings -> Apps & Connectors**
2. Click **"Add new connector"**
3. Enter name: **HyPeMa** and URL: `https://mcp.hypema.app/mcp`
4. ChatGPT opens the HyPeMa login page -- sign in and approve
5. Enable HyPeMa in your chat via the connectors toggle

---

## Cursor / VS Code / GitHub Copilot

IDE-based AI tools support MCP via config files. These use API key authentication (no OAuth popup).

### Cursor

Create or edit `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "hypema": {
      "url": "https://mcp.hypema.app/mcp",
      "headers": {
        "Authorization": "Bearer hpm_live_your_key_here"
      }
    }
  }
}
```

### VS Code / GitHub Copilot

Open Settings (JSON) and add:

```json
{
  "mcp": {
    "servers": {
      "hypema": {
        "type": "http",
        "url": "https://mcp.hypema.app/mcp",
        "headers": {
          "Authorization": "Bearer hpm_live_your_key_here"
        }
      }
    }
  }
}
```

Get your API key at **Settings -> API Keys** in the HyPeMa web app. Keys start with `hpm_live_`.

---

## Other Platforms

HyPeMa works with any MCP-compatible client. Here are configs for additional platforms.

### OpenClaw

```bash
openclaw mcp add hypema --url https://mcp.hypema.app/mcp
```

### Windsurf (Codeium)

```json
{
  "mcpServers": {
    "hypema": {
      "serverUrl": "https://mcp.hypema.app/mcp",
      "headers": {
        "Authorization": "Bearer hpm_live_your_key_here"
      }
    }
  }
}
```

### OpenAI Agents SDK (Python)

```python
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.hypema.app/mcp",
        "authorization": {
            "token": "Bearer <your_oauth_token>"
        }
    }],
    input="Find 5 CTOs at fintech companies in Germany"
)
```

### Also supported

- JetBrains IDEs
- Zed
- Cline
- Goose
- Google Gemini (ADK)

All use the same URL: `https://mcp.hypema.app/mcp` with an API key in the Authorization header.

---

## Tools Reference

HyPeMa exposes **15 tools** to your AI assistant. Each tool maps to a REST API endpoint and uses your HyPeMa token balance for AI operations.

| Tool | Type | Read-only | Cost | Description |
|------|------|-----------|------|-------------|
| `research_company` | AI-powered | Yes | ~25-40 tokens | Research a company by URL using AI web search. Returns industry, product, value proposition, leadership, and customer profile. Accepts `effort` to override Company Research default. |
| `generate_leads` | AI-powered | No | ~30-60 tokens | Find real prospect leads by searching the web for people matching your criteria (industry, region, role, company size). Accepts `effort` to override Lead Generation default. |
| `list_leads` | CRUD | Yes | Free | List all leads with optional filtering by status, search, and pagination. |
| `get_lead` | CRUD | Yes | Free | Get full details of a specific lead by ID. |
| `create_lead` | CRUD | No | Free | Create a lead manually. Requires `email` and `company`; `first_name` and `last_name` are optional. Use `lead_type` for `person`, `role_inbox`, or `company_inbox` leads. |
| `update_lead` | CRUD | No | Free | Update an existing lead's information (name, company, role, status, notes). |
| `delete_lead` | CRUD (destructive) | No | Free | Permanently delete a lead. This action cannot be undone. |
| `preview_emails` | AI-powered | Yes | ~2-10 tokens/preview | Preview email drafts without saving. Use to review and iterate with feedback before committing. Cost depends on Secret Sauce mode and thinking depth. Accepts `effort` to override Email default. |
| `generate_email` | AI-powered | No | ~2-10 tokens | Generate a hyper-personalized cold email for a specific lead. Cost depends on Secret Sauce mode: ~2 (default), ~6 (reply\_rate), ~10 (positive\_reply\_rate). Accepts `effort` to override Email default. |
| `generate_email_batch` | AI-powered | No | ~2-10 tokens/lead | Generate personalized emails for all leads in a group at once. Cost per lead depends on Secret Sauce mode. Accepts `effort` to override Email default. |
| `get_draft_payload` | Utility | No | Free | Get a ready-to-send email payload with `to`, `subject`, `textBody`, and `htmlBody`. Marks lead as drafted. Use with Gmail/Outlook MCP (or any email-sending MCP) to send. |
| `list_campaigns` | CRUD | Yes | Free | List all outreach campaigns with inline stats (lead count, emails sent, reply rate). Campaigns are auto-created when you generate emails. |
| `get_campaign` | CRUD | Yes | Free | Get details and stats for a single campaign by ID. |
| `get_campaign_stats` | CRUD | Yes | Free | Aggregated metrics for a campaign: totalLeads, emailsGenerated, emailsSent, repliesReceived, replyRate %. |
| `check_usage` | Utility | Yes | Free | Check your remaining HyPeMa token balance, usage, and plan limit. |

### Role and company inbox leads

`create_lead` supports named people and inbox-style leads. Do not invent a name just to create a lead.

- For a real person, use `lead_type: "person"` and include `first_name` and/or `last_name` when known.
- For a role inbox such as `hello@`, `sales@`, or `contact@`, use `lead_type: "role_inbox"` and omit `first_name` and `last_name`.
- For a general company inbox such as `info@`, use `lead_type: "company_inbox"` and omit `first_name` and `last_name`.
- Drafts for role or company inboxes use neutral greetings like `Hi team,` or `Hi Bespoke AI Studio team,`.

Example:

```json
{
  "email": "contact@bespokeaistudio.ai",
  "company": "Bespoke AI Studio",
  "role_title": "AI automation / AI engineering practitioner",
  "country": "Salt Lake City, UT, United States",
  "lead_type": "role_inbox",
  "notes": "Bespoke AI Studio offers AI automation agents and implementation support."
}
```

### Effort parameter

AI-powered tools accept an optional `effort` parameter (`max`, `xhigh`, `high`, `medium`, `low`) to override the per-operation thinking depth default from Settings. Each operation type (Email, Lead Generation, Company Research) has its own default configured in Settings -> AI Settings. `xhigh` and `max` are Opus 4.7 only.

### Token costs

CRUD operations (list, get, create, update, delete) and check_usage are free. AI-powered operations (research, generate leads, generate emails) consume tokens. Costs vary by Secret Sauce mode and thinking depth. 100 tokens = 1 EUR. Free tier: 500 tokens one-time credit on signup (no monthly reset). Pro tier: 5,000 tokens/month.

---

## Troubleshooting

**Q: OAuth login opens but nothing happens after I authorize**
A: Make sure third-party cookies are enabled for the OAuth callback. In some browsers, the popup may be blocked -- check your browser's popup blocker settings. Try again in a new tab.

**Q: I get "Invalid or expired OAuth token"**
A: Your session has expired. Disconnect and reconnect the HyPeMa connector in your AI platform's settings. This will trigger a fresh OAuth login.

**Q: "Authentication required" on every tool call**
A: Your API key or OAuth token isn't being sent. For API key setups (Cursor, VS Code), make sure the Authorization header is set to "Bearer hpm_live_..." in your MCP config.

**Q: Tools appear but return errors**
A: Check your token balance with check_usage. If you're out of tokens, upgrade your plan at Settings -> Billing. AI operations (research, lead generation, email) consume tokens.

**Q: Can I use both the web app and MCP at the same time?**
A: Yes! They share the same data and token pool. Leads created via MCP appear in the web app and vice versa.

**Q: Which AI platforms support MCP?**
A: Claude.ai, Claude Desktop, Claude Code, ChatGPT (Developer Mode), Cursor, VS Code, OpenClaw, Windsurf, JetBrains IDEs, Zed, Cline, Goose, and Google Gemini (ADK). Any MCP-compatible client works.

---

Still stuck? Contact support at **support@hypema.app**