# Nyne.ai MCP Server

> Connect AI assistants like ChatGPT and Claude directly to Nyne.ai's people data workflows using the Model Context Protocol (MCP).

HTML version: https://api.nyne.ai/documentation/mcp

**Model Context Protocol (MCP)** is an open standard that enables AI assistants to securely connect to external data sources and tools - a universal plugin system for AI. The **hosted Nyne.ai MCP Server** brings Nyne.ai's common people search and enrichment workflows directly into your assistant conversations:

- **People Search** - semantic search across millions of profiles by company, role, location, or keywords.
- **Profile Enrichment** - comprehensive person profiles with contact info, work history, education, and socials.
- **AI-Powered Insights** - ask natural-language questions about profiles and get intelligent analysis.

## Coverage

The hosted MCP exposes a curated subset of Nyne.ai workflows: people search, person enrichment, targeted lookup fields, person newsfeed, person Q&A, company search, and company enrichment. For the broader endpoint surface, point agents at the machine-readable docs first:

- llms.txt: https://api.nyne.ai/llms.txt
- Agent manifest: https://api.nyne.ai/.well-known/nyne-api.json

## Available tools

### person_search

Search for people from a natural-language query, structured filters, or pagination cursor/request_id.

- Search by query
- Search by structured filters or docid whitelist
- Request contact fields and profile scoring
- Up to 100 results per query
- Requires 'search' product access

Example: *"Find software engineers at Google in San Francisco"*

### person_enrichment

Get detailed profile information for a person using email, phone, name, or social profile URL. This is also how you look up specific contact fields: the enrichment result already includes best work email, personal email, mobile, headline, current company, current title, and photo URL, so use it when you only need one or a few of those values.

- Lookup by email, phone, social URL, or name
- Comprehensive contact information (best work email, mobile, title, headline, photo URL, and more)
- Use for targeted field lookups: the profile already includes the individual fields
- Work history and education
- Social media profiles
- Requires 'enrichment' product access

Example: *"Get the profile for john@example.com"*

### person_newsfeed

Fetch recent social posts and activity for a social profile URL.

- Supports LinkedIn/social URLs
- Optional limit and posts_after date
- Requires newsfeed product access

### person_ask

Ask AI-powered questions about a person's profile using natural language.

- Natural language Q&A
- AI-powered analysis
- Context-aware answers
- Synthesizes multiple data points
- Requires 'enrichment' product access

Example: *"What is this person's current role and experience?"*

### company_search

Search for companies by industry or website keyword, optionally filtered by location.

### company_enrichment

Enrich a company from domain, email, phone, or social profile URL.

## Why use Nyne.ai MCP?

- **Instant access** - no code required. Connect once and query Nyne.ai data from ChatGPT or Claude.
- **Secure** - uses your existing Nyne.ai API credentials. All requests are authenticated and logged.
- **Natural language** - ask in plain English. The assistant handles the technical details.
- **Accurate** - real-time data from Nyne.ai's people intelligence workflows, no integration code.
- **Cost-effective** - uses your existing Nyne.ai subscription and credit balance. No additional fees.
- **Comprehensive** - the hosted MCP is a curated subset; the full HTTP API is covered by llms.txt + the manifest.

## Integration guides

### ChatGPT

1. Open ChatGPT and go to **Settings → Connectors** (custom connectors require Developer mode; Plus, Pro, Business, or Enterprise).
2. Click **Add custom connector**.
3. Enter the Nyne.ai MCP endpoint `https://api.nyne.ai/mcp`.
4. When prompted for authentication, choose **OAuth** (recommended). The flow uses:

   ```
   Authorization URL: https://api.nyne.ai/mcp/oauth/authorize
   Token URL: https://api.nyne.ai/mcp/oauth/token
   ```

5. ChatGPT handles Dynamic Client Registration and sends the public OAuth `client_id` during token and refresh requests.
6. OAuth returns short-lived access tokens plus rotating refresh tokens so ChatGPT can silently renew access without asking you to log in again.
7. Do not choose ChatGPT's **Access token/API key** Bearer option for Nyne API credentials. Nyne API credentials are a key/secret pair; ChatGPT's single Bearer field cannot send both values.
8. If OAuth is unavailable, select **No authentication** only for discovery. Tool execution requires OAuth or a client/proxy that can send `X-API-Key` and `X-API-Secret` headers.
9. Click **Save**. ChatGPT discovers Nyne.ai tools from the manifest.

### Claude Desktop

1. Open or create the MCP configuration file at `~/.claude/mcp.json`.
2. Add Nyne.ai to your configuration:

   ```json
   {
     "mcpServers": {
       "nyne": {
         "url": "https://api.nyne.ai/mcp",
         "headers": {
           "X-API-Key": "your_nyne_api_key",
           "X-API-Secret": "your_nyne_api_secret"
         }
       }
     }
   }
   ```

3. Restart Claude Desktop. Nyne.ai tools are now available.

### Other MCP clients

- **Discovery endpoint:** `https://api.nyne.ai/.well-known/mcp`
- **MCP endpoint:** `https://api.nyne.ai/mcp`
- **OAuth authorization server metadata:** `https://api.nyne.ai/.well-known/oauth-authorization-server`
- **OAuth protected resource metadata:** `https://api.nyne.ai/.well-known/oauth-protected-resource`
- **Authentication:** OAuth2 (recommended) via `/mcp/oauth/authorize` and `/mcp/oauth/token`; or the `X-API-Key` + `X-API-Secret` headers.

## Pricing & usage

Nyne.ai MCP uses your existing subscription and credit balance. MCP tools use the same credit costs as the REST API.

| Tool | Uses credits like | Required product |
| --- | --- | --- |
| `person_search` | Person Search | Search |
| `person_enrichment` | Person Enrichment | Enrichment |
| `person_newsfeed` | URL Newsfeed | Newsfeed |
| `person_ask` | Person Ask | Enrichment |
| `company_search` | Company Search | Search |
| `company_enrichment` | Company Enrichment | Enrichment |

Per-tool credit costs are loaded from your account and shown in the API reference. MCP requests count toward your API key's rate limits and quotas, just like REST calls.

## Async processing & polling

MCP tools use the same async request pattern as the REST API. Your assistant handles the polling automatically - you just ask naturally.

```
# 1. Invoke tool through JSON-RPC
POST /mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "person_search",
    "arguments": { "query": "engineers at Google", "limit": 10 }
  }
}

# Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"pending\",\"request_id\":\"abc123...\",\"endpoint\":\"person_search\"}"
      }
    ]
  }
}

# 2. Poll for results
GET /mcp/status?request_id=abc123...

# Response while processing:
{ "status": "pending", "message": "Processing..." }

# Response when complete:
{
  "status": "completed",
  "results": [],
  "completed_at": "2025-10-10T10:30:00Z"
}
```

## Next steps

- [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md)
- [API Reference](https://api.nyne.ai/documentation.md)