# Zintlr MCP Server
Remote MCP (Model Context Protocol) server for LLM integration with Zintlr sales intelligence platform.
## Overview
This server allows LLM users to connect to Zintlr directly from their MCP client's Settings → Connectors interface by simply pasting the server URL.
```
LLM Client → MCP Server (mcp.zintlr.com) → Zintlr APIs (api.zintlr.com)
```
## Features
- **Remote MCP Protocol**: Works with any MCP-compatible LLM client
- **OAuth Passthrough**: Redirects to Zintlr login, stores existing JWT tokens
- **Direct API Access**: Bypasses auth.zintlr.com proxy, calls api.zintlr.com directly
- **13 Tools**: Search prospects, get profiles, unlock contacts, and more
## Quick Start
### 1. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` with your secrets:
- `CIPHER_SECRET`: Same as `process.env.CIPHER` in Next.js proxy
- `CAPTCHA_TOKEN`: Same as `CAPTCHA_TOKEN` in Next.js proxy
- `MCP_SERVER_URL`: Public URL of this server
### 2. Run with Docker
```bash
docker-compose up -d
```
### 3. Run Locally (Development)
```bash
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```
## User Setup
1. Open your MCP-compatible LLM client (e.g., Claude, etc.)
2. Go to **Settings → Connectors**
3. Click **"Add custom connector"**
4. Enter URL: `https://mcp.zintlr.com` (your deployed URL)
5. Complete OAuth flow (redirects to Zintlr login)
6. Done! Tools are now available in your LLM
## Available Tools
| Tool | Description |
|------|-------------|
| `search_prospects` | Search people/companies with filters |
| `search_by_company_name` | Company name autocomplete |
| `search_by_company_domain` | Find company by domain |
| `search_by_job_title` | Job title autocomplete |
| `search_by_location` | Location autocomplete |
| `search_by_technology` | Tech stack autocomplete |
| `get_person_profile` | Get detailed person info |
| `get_company_profile` | Get detailed company info |
| `unlock_contact_info` | Reveal email/phone (uses credits) |
| `fetch_profile` | Get current user's profile |
| `get_search_history` | View recent searches |
| `get_saved_searches` | View saved search templates |
| `save_search` | Save a search for later |
## Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM Client │────▶│ MCP Server │────▶│ Zintlr API │
│ (User's app) │ │ (This service) │ │ api.zintlr.com │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ JSON-RPC │ HTTP + Decrypted JWT
│ + Session ID │ + Headers (Auth, visitor-id)
│ │
```
### Authentication Flow
1. User adds connector URL in LLM client
2. LLM client requests OAuth metadata from `/.well-known/oauth-authorization-server`
3. User redirected to `/oauth/authorize` → Zintlr login
4. After login, Zintlr redirects to `/oauth/callback` with JWT tokens
5. MCP server stores tokens in Redis, returns session ID to LLM client
6. LLM client uses session ID as Bearer token for MCP requests
7. MCP server decrypts tokens, calls Zintlr API directly
### Proxy Bypass
This server replicates the Next.js proxy logic (`auth.zintlr.com`):
- Decrypts JWT tokens using `verify_and_decrypt_jwt(token, CIPHER)`
- Sets `Authorization` header with decrypted access_token
- Sets `visitor-id` and `client-ip-address` headers
- Adds decrypted `key` to request body
- Calls `api.zintlr.com` directly
## API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | POST | MCP JSON-RPC endpoint |
| `/` | GET | Server info |
| `/.well-known/oauth-authorization-server` | GET | OAuth metadata |
| `/oauth/authorize` | GET | Start OAuth flow |
| `/oauth/callback` | GET | OAuth callback from Zintlr |
| `/oauth/token` | POST | Exchange code for token |
| `/oauth/revoke` | POST | Revoke token (logout) |
| `/health` | GET | Health check |
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `ZINTLR_API_BASE_URL` | `https://api.zintlr.com` | Direct API URL |
| `ZINTLR_FRONTEND_URL` | `https://auth.zintlr.com` | Frontend for OAuth |
| `CIPHER_SECRET` | - | JWT decryption secret |
| `CAPTCHA_TOKEN` | - | API authentication token |
| `MCP_SERVER_URL` | `https://mcp.zintlr.com` | This server's public URL |
| `REDIS_URL` | `redis://localhost:6379` | Redis for sessions |
| `SESSION_EXPIRE_SECONDS` | `3600` | Session TTL (1 hour) |
| `HOST` | `0.0.0.0` | Server host |
| `PORT` | `8000` | Server port |
| `DEBUG` | `false` | Debug mode |
## Testing
### Test MCP Endpoint
```bash
# Initialize
curl -X POST http://localhost:8000/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# List tools
curl -X POST http://localhost:8000/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```
### Test Health
```bash
curl http://localhost:8000/health
```
## Deployment
### Docker
```bash
docker build -t zintlr-mcp-server .
docker run -p 8000:8000 --env-file .env zintlr-mcp-server
```
### Docker Compose
```bash
docker-compose up -d
```
### Production Checklist
- [ ] Set `DEBUG=false`
- [ ] Configure proper `MCP_SERVER_URL` with HTTPS
- [ ] Set secure `CIPHER_SECRET` and `CAPTCHA_TOKEN`
- [ ] Configure Redis persistence
- [ ] Set up reverse proxy (nginx) with SSL
- [ ] Configure DNS for `mcp.zintlr.com`
## License
Proprietary - Zintlr
