# Nyne.ai MCP Quick Start

> Get up and running with Nyne.ai MCP in three minutes.

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

## What you'll need

- A Nyne.ai account with an active subscription
- API credentials (API Key + Secret)
- An MCP-capable client - Claude (Code or Desktop), ChatGPT, Cursor, VS Code, Windsurf, Zed, or a CLI agent

## Agent discovery links

If an agent is integrating without prior context, point it at the machine-readable docs before the HTML pages - that reduces bad endpoint selection and incomplete generated code.

```
llms.txt:               https://api.nyne.ai/llms.txt
Agent manifest:         https://api.nyne.ai/.well-known/nyne-api.json
Example endpoint (md):  https://api.nyne.ai/documentation/person/enrichment.md
```

The hosted MCP is a curated subset focused on person and company search, enrichment, lookup fields, newsfeed, and profile Q&A. For broader coverage, use the manifest and endpoint markdown docs first.

## Connect your client

The Nyne.ai MCP server is remote (hosted) - there is nothing to install. Point any MCP-capable client at `https://api.nyne.ai/mcp` and authenticate with one of:

- **OAuth 2.0** (recommended) - interactive login, no keys to store. Best for hosted assistants like ChatGPT and Claude Desktop.
- **API Key headers** - send `X-API-Key` and `X-API-Secret`. Best for editors and CLIs that read a config file.

Swap `YOUR_API_KEY` / `YOUR_API_SECRET` for the credentials from your Nyne.ai dashboard. Treat them like passwords - prefer your client's secret-input or environment-variable support over committing them to a shared file.

### Hosted assistants

#### ChatGPT

1. Open ChatGPT → **Settings → Connectors** (custom connectors require Developer mode; Plus, Pro, Business, or Enterprise).
2. Click **Add custom connector** and enter `https://api.nyne.ai/mcp`.
3. Choose **OAuth** and complete Nyne.ai login. The OAuth endpoints are:

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

4. ChatGPT handles Dynamic Client Registration and sends the public OAuth `client_id` during token and refresh requests.
5. OAuth returns short-lived access tokens plus rotating refresh tokens so ChatGPT can silently renew access without asking you to log in again.
6. 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.
7. ChatGPT cannot send custom `X-API-Key` headers, so OAuth is required for hosted MCP tool execution in ChatGPT.
8. Save and test.

#### Claude Desktop

1. Open **Settings → Connectors → Add custom connector**.
2. Name it `nyne`, set the URL to `https://api.nyne.ai/mcp`, and complete the **OAuth** login.
3. Prefer API keys? The Connectors UI is OAuth-only, so bridge with `mcp-remote` in `claude_desktop_config.json` (Settings → Developer → Edit Config):

   ```json
   {
     "mcpServers": {
       "nyne": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://api.nyne.ai/mcp",
           "--header",
           "X-API-Key:${API_KEY}",
           "--header",
           "X-API-Secret:${API_SECRET}"
         ],
         "env": { "API_KEY": "YOUR_API_KEY", "API_SECRET": "YOUR_API_SECRET" }
       }
     }
   }
   ```

4. Restart Claude Desktop.

### Command-line tools

#### Claude Code

Run:

```bash
claude mcp add --transport http nyne https://api.nyne.ai/mcp \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "X-API-Secret: YOUR_API_SECRET"
```

Add `-s user` before the name to register it globally instead of per-project.

#### Gemini CLI

Run:

```bash
gemini mcp add --transport http \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  nyne https://api.nyne.ai/mcp
```

In `~/.gemini/settings.json` the URL key is `httpUrl` (not `url`) for HTTP servers.

#### Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.nyne]
url = "https://api.nyne.ai/mcp"
http_headers = { "X-API-Key" = "YOUR_API_KEY", "X-API-Secret" = "YOUR_API_SECRET" }
```

Codex uses `http_headers` (not `headers`). On older builds, add `experimental_use_rmcp_client = true` at the top of the file.

#### GitHub Copilot CLI

Add to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "nyne": {
      "type": "http",
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" },
      "tools": ["*"]
    }
  }
}
```

#### OpenCode

Add to `opencode.json`:

```json
{
  "mcp": {
    "nyne": {
      "type": "remote",
      "url": "https://api.nyne.ai/mcp",
      "enabled": true,
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

OpenCode nests servers under `mcp` (not `mcpServers`) and needs `type: "remote"`.

### Editors & IDEs

#### Cursor

Add to `~/.cursor/mcp.json`:

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

#### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "nyne": {
      "type": "http",
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "${input:nyne-key}", "X-API-Secret": "${input:nyne-secret}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "nyne-key", "description": "Nyne.ai API Key", "password": true },
    { "type": "promptString", "id": "nyne-secret", "description": "Nyne.ai API Secret", "password": true }
  ]
}
```

The top-level key is `servers` (not `mcpServers`). The `inputs` block prompts for each secret on first run; hardcode the values instead if you prefer.

#### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "nyne": {
      "serverUrl": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

Windsurf uses `serverUrl` (not `url`) for remote servers.

#### Zed

Add to your Zed `settings.json`:

```json
{
  "context_servers": {
    "nyne": {
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

Needs a recent Zed with native HTTP MCP support; older builds require the `mcp-remote` stdio bridge.

#### JetBrains (Junie)

Add to `.junie/mcp/mcp.json`:

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

Junie supports header auth. The plain AI Assistant remote-server form is URL-only - use Junie's config or an `mcp-remote` bridge there.

## Test it out

Try these example queries in your AI assistant:

**Search for people**

```
"Find software engineers at Google in Seattle"
"Show me CTOs in the fintech industry"
"Search for product managers with AI experience"
```

**Get profile details**

```
"Get the profile for john@company.com"
"Find contact info from this social profile URL"
"Enrich this phone: (415) 555-1234"
```

**Ask AI questions**

```
"What is this person's current role?"
"Does this person have sales experience?"
"What companies has this person worked for?"
```

That's it - your AI assistant can now search and analyze Nyne.ai's people data directly.

## Quick reference

| What | Value |
| --- | --- |
| Discovery URL | `https://api.nyne.ai/.well-known/mcp` |
| MCP endpoint | `https://api.nyne.ai/mcp` |
| Auth method | OAuth2 (recommended) via `/mcp/oauth` • `X-API-Key` + `X-API-Secret` for clients that support custom headers |
| Protocol version | `2024-11-01` |

## Credits & pricing

MCP uses the same credit costs as the REST API.

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

MCP uses your existing Nyne.ai credits and respects your API rate limits. Costs are loaded from your account and update automatically if they change.

## Async processing

1. Tool invocation returns `HTTP 202` with a `request_id`.
2. Poll `GET /mcp/status?request_id=xxx` every 2-3 seconds.
3. When status is `completed`, results are included in the response.

Polling is automatic - your AI assistant handles it for you; just ask questions naturally and it waits for results.

## Next steps

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