# Invenitor MCP

People search and contact lookup for apps and agents.

Endpoint: `https://api.invenitor.com/mcp` (Streamable HTTP, POST only).

## Connect

Prefer OAuth. It opens one consent screen and gives the host a short-lived
token. Use an API key only when the host cannot do OAuth.

### OAuth (recommended)

1. Read the resource metadata at `https://api.invenitor.com/.well-known/oauth-protected-resource`.
2. Read the authorization server metadata at `https://api.invenitor.com/.well-known/oauth-authorization-server`.
3. Register the host at `https://api.invenitor.com/oauth/register` with `client_name`, `redirect_uris`, and an optional `logo_uri`. Keep the returned `client_id`.
4. Build a PKCE `code_challenge` (S256) and open:
   `https://people.invenitor.com/mcp/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>&code_challenge=<challenge>&code_challenge_method=S256&state=<state>&scope=mcp`
5. The customer signs in and presses **Allow**. The consent screen redirects to `redirect_uri` with `code` and `state`.
6. Exchange the code at `https://api.invenitor.com/oauth/token`:
   `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`.
7. Send `Authorization: Bearer <access_token>` to the MCP endpoint. The token lasts one hour. Refresh by repeating the consent flow.

The customer can see and disconnect every connected app at
`https://people.invenitor.com/mcp`.

### API key (fallback)

1. If this host already has a `pf_live_` key for Invenitor, use it. Do not ask again.
2. If not, ask once: paste the secret from https://people.invenitor.com/settings/api-keys (shown once). Never put the key in a query string.
3. Add the remote MCP server named `invenitor` with header `Authorization: Bearer <key>`.

## Your job

1. Prefer OAuth. Use an API key only when OAuth is unavailable.
2. Call `get_balance` to confirm. Then wait for a LinkedIn or GitHub profile before `find_contact`.
3. Confirm with the person before `find_contact`. 1 credit only when we return an email, a phone, or both. Timeouts do not spend. Only share contact details the tool returned.

Mailbox: hello@invenitor.com. Docs: https://invenitor.com/docs

## Tools

| Tool | Spends | Notes |
|------|--------|-------|
| get_balance | 0 | Credits left |
| find_contact | 1 when complete | Needs a LinkedIn or GitHub profile URL. A name helps. |
| people_search | 20 when it finds someone | People from a plain sentence. Free if it finds nobody. |
| list_searches | 0 | Your saved searches |
| get_search | 0 | People from one saved search |
| open_contact | 1 when found | Email or phone for one person from a search |
| list_contacts | 0 | Contacts you already opened |
| list_shortlists | 0 | Your lists |
| get_shortlist | 0 | People in one list |
| create_shortlist | 0 | Start a list |
| add_to_shortlist | 0 | Add people from a search |

## Cursor (`~/.cursor/mcp.json` or Settings → MCP)

OAuth: add the server URL `https://api.invenitor.com/mcp`. Cursor opens the consent screen.

API key fallback:

```json
{
  "mcpServers": {
    "invenitor": {
      "url": "https://api.invenitor.com/mcp",
      "headers": {
        "Authorization": "Bearer pf_live_YOUR_KEY"
      }
    }
  }
}
```

## Claude Code

OAuth: `claude mcp add --transport http invenitor https://api.invenitor.com/mcp` and follow the consent screen.

API key fallback:

```bash
claude mcp add --transport http invenitor https://api.invenitor.com/mcp --header "Authorization: Bearer pf_live_YOUR_KEY"
```

## ChatGPT

Settings → Apps & Connectors → Advanced → Developer mode → Create. Name `invenitor`. URL `https://api.invenitor.com/mcp`. Choose OAuth when offered. Otherwise use a Bearer token.

## Gemini and Antigravity

Command palette → MCP add → HTTP. URL `https://api.invenitor.com/mcp`. Name `invenitor`. Use OAuth when offered, else a Bearer header.

`~/.gemini/settings.json` or `.agents/mcp_config.json`:

```json
{
  "mcpServers": {
    "invenitor": {
      "httpUrl": "https://api.invenitor.com/mcp",
      "headers": {
        "Authorization": "Bearer pf_live_YOUR_KEY"
      }
    }
  }
}
```

## VS Code (Copilot)

`.vscode/mcp.json`:

```json
{
  "servers": {
    "invenitor": {
      "type": "http",
      "url": "https://api.invenitor.com/mcp"
    }
  }
}
```

Use a Bearer header only when the host cannot do OAuth.

## Windsurf and Codex

Same remote URL and OAuth consent. Windsurf: MCP settings → HTTP server. Codex: `codex mcp add invenitor --url https://api.invenitor.com/mcp`.

## Do not

- Guess emails or phones
- Put the key or token in the URL
- Run `find_contact` without a profile link and a confirm