# 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 10 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
```

---

## 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.

### Option A: Add via CLI command

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

Claude Code opens a browser for OAuth login automatically on first use.

### Option B: Add with API key (skip OAuth)

```bash
claude mcp add hypema \
  --transport http \
  --header "Authorization: Bearer hpm_live_your_key_here" \
  https://mcp.hypema.app/mcp
```

### Option C: Edit config file directly

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 10 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 **10 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 target audience. |
| `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). |
| `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 new lead manually with email, name, company, role, and notes. |
| `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. |
| `generate_email` | AI-powered | No | ~15-25 tokens | Generate a hyper-personalized cold email for a specific lead using AI. |
| `generate_email_batch` | AI-powered | No | ~15-25 tokens/lead | Generate personalized emails for all leads in a group at once. |
| `check_usage` | Utility | Yes | Free | Check your remaining HyPeMa token balance, usage, and plan limit. |

### Token costs

CRUD operations (list, get, create, update, delete) and check_usage are free. AI-powered operations (research, generate leads, generate emails) consume tokens. 100 tokens = 1 EUR. Free tier: 500 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**