# Connect an agent

Add the OSINTverse MCP server to Claude, Claude Code, ChatGPT, Cursor, VS Code, a JSON config, or the Messages API, with OAuth or an API key.

URL: https://osintverse.com/docs/mcp/setup

Every client uses the same endpoint, `https://osintverse.com/mcp`. People sign in with OAuth; scripts send an API key.

**Claude**

1. In Claude (web, desktop, or mobile) open **Settings → Connectors** and choose **Add custom connector**.
2. Paste `https://osintverse.com/mcp` and click **Connect**.
3. Sign in to OSINTverse. On the consent screen pick the wallet to bill (personal or a team you can search in) and set a daily cap for this agent. The agent starts in sandbox mode, so nothing is charged until you switch it to live.
4. Ask Claude to quote and run a lookup. Paid tools ask for confirmation; reads do not.

Claude identifies itself with a Client ID Metadata Document, so there is nothing to register on your side.

**Claude Code**

```bash title="Add the server"
claude mcp add --transport http osintverse https://osintverse.com/mcp
```

Run `/mcp` inside Claude Code to sign in. The prompts appear as `/osintverse:investigate_email`, `/osintverse:investigate_username`, `/osintverse:investigate_domain`, `/osintverse:investigate_phone`, and `/osintverse:investigate_wallet`.

For scripts, pass an API key instead of signing in:

```bash title="API key instead of OAuth"
claude mcp add --transport http osintverse https://osintverse.com/mcp --header "Authorization: Bearer ov_your_api_key"
```

**ChatGPT**

ChatGPT on the web can add OSINTverse as a custom MCP server. Whether you can add one depends on your ChatGPT plan, and in a Business or Enterprise workspace an admin may need to allow it.

1. In ChatGPT open **Plugins**, select **+**, then **Add custom MCP server**.
2. Name it `OSINTverse`, paste `https://osintverse.com/mcp` as the server URL, and choose **OAuth** for authentication.
3. Review the warning and select **I understand and want to continue**, then **Create as a plugin**.
4. Sign in to OSINTverse when asked. On the consent screen pick the wallet to bill and set a daily cap. ChatGPT starts in sandbox mode, so nothing is charged until you switch it to live.
5. Review the tools ChatGPT found and install the plugin, then turn it on in a chat.

If your ChatGPT shows **Settings → Apps → Advanced settings** instead of Plugins, turn on **Developer mode** there, then use **Create** with the same URL and OAuth.

ChatGPT identifies itself with a Client ID Metadata Document, so nothing needs registering on your side. It asks before running tools that are not marked read-only, which includes every paid lookup.

**Cursor**

Open **Settings → MCP** and add a server with URL `https://osintverse.com/mcp`, or use the one-click link on the [agents page](https://osintverse.com/agents). Cursor starts the OAuth sign-in on first use.

**VS Code**

VS Code 1.99 or later with MCP support: run **MCP: Add Server**, choose **HTTP**, and enter `https://osintverse.com/mcp`. Or add it to `.vscode/mcp.json`:

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

**JSON**

Any client that reads an `mcpServers` config:

```json title="OAuth (sign-in starts on first request)"
{
  "mcpServers": {
    "osintverse": { "type": "http", "url": "https://osintverse.com/mcp" }
  }
}
```

```json title="API key (scripts and servers)"
{
  "mcpServers": {
    "osintverse": {
      "type": "http",
      "url": "https://osintverse.com/mcp",
      "headers": { "Authorization": "Bearer ov_your_api_key" }
    }
  }
}
```

Create keys under [Dashboard → API keys](https://osintverse.com/dashboard/api). Personal keys bill your wallet; team keys bill the team.

**Messages API**

The Anthropic Messages API can call the server directly with the MCP connector. Send your `ov_` key as the authorization token:

```json title="Request body"
{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://osintverse.com/mcp",
      "name": "osintverse",
      "authorization_token": "ov_your_api_key"
    }
  ],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "osintverse" }],
  "messages": [
    {
      "role": "user",
      "content": "Quote, then run a LeakRadar email search for user@example.com and file it in a case."
    }
  ]
}
```

The MCP connector needs the `anthropic-beta: mcp-client-2025-11-20` header. Restrict the toolset with `allowed_tools` if the agent should only read.

## Your first five minutes

Every new connection starts in **sandbox mode**: all the tools work, but searches return sample data and nothing is charged. Ask the agent to walk through these. Each step is one tool call.

1. **`whoami`**: which wallet it bills, the scopes you granted, both daily caps, and `mode: "sandbox"`.
2. **`list_providers`** with an `input_type` such as `email`: who can look it up and at what price.
3. **`quote_search`** (or **`quote_bulk_search`** for several identifiers or providers): what the lookup would cost live, and whether the balance and caps allow it.
4. **`create_case`**, then **`run_search`** or **`run_bulk_search`** with that `case_id`: runs the lookup on sample data and files it in one go.
5. **`get_case`**: everything filed so far, grouped by run.

When the workflow looks right, open **Dashboard → API keys → Agents** and choose **Go live** for that agent. Searches then return real results and charge your wallet, inside your caps. Every call, sandbox or live, shows up under **Recent agent calls**.

## Which credential to use

| Credential    | Who it identifies                      | Scopes                                                                                                         | Where it bills                                                            |
| ------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| OAuth sign-in | You, per connected app                 | `osint:read`, `search:run`, `cases:write` as granted                                                           | The wallet chosen on the consent screen                                   |
| `ov_` API key | The key's owner (personal) or the team | Set by the key's access level: read only (`osint:read`), search and read (+ `search:run`), or full (all three) | Same wallet as the REST API, within the key's own daily cap if it has one |

Both are limited by the workspace's daily agent cap and the per-call rate limits (60 tool calls and 10 paid searches per minute). OAuth connections can also have their own cap that counts only their spend.

## Demo endpoint

`https://osintverse.com/mcp/demo` needs no credential, returns fixed sample results, and never bills. Use it to confirm your client connects before you sign in.

- [Get an API key](https://osintverse.com/dashboard/api)
- [OpenAPI spec](https://osintverse.com/openapi.json) and [Swagger UI](https://apiv1.osintverse.com/docs)
- [API sandbox (free, mock data)](https://osintverse.com/developers/sandbox)
- [Pricing](https://osintverse.com/pricing.json)