> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agentic-id.icustomer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Run the Agentic ID MCP server next to your agent and call every product as a tool.

The Agentic ID MCP server is a local program. Your MCP client starts it and talks to it over stdio. The server calls the Agentic ID API over HTTPS for you.

| Setting | Value |
| - | - |
| Transport | stdio (JSON-RPC 2.0, one message per line) |
| Command | `node <path>/plugins/agentic-id/server/mcp.mjs` |
| Requirements | Node.js 18 or later. No packages to install. |
| MCP protocol versions | `2025-06-18`, `2025-03-26`, `2024-11-05` |
| Auth | A stored sign-in, or an API key in the environment |

> [!NOTE]
>
> There is no remote (HTTP) MCP endpoint today. The server runs on your machine. In Claude Code, the [plugin](https://docs-agentic-id.icustomer.ai/claude-code-plugin.md) starts it for you.

## Connect

**1. Get the server**

The server ships inside the Claude Code plugin repository. Clone it and note the absolute path of `plugins/agentic-id/server/mcp.mjs`.

```bash theme={null}
git clone https://github.com/icustomerai/agentic-id-plugin
```

**2. Add it to your client**

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add agentic-id \
>   --env AGENTIC_ID_URL=https://YOUR_AGENTIC_ID_HOST \
>   --env AGENTIC_ID_API_KEY_FILE=/absolute/path/to/key-file \
>   -- node /absolute/path/to/agentic-id-plugin/plugins/agentic-id/server/mcp.mjs
> ```

> [tab] Generic JSON config
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "agentic-id": {
>       "command": "node",
>       "args": ["/absolute/path/to/agentic-id-plugin/plugins/agentic-id/server/mcp.mjs"],
>       "env": {
>         "AGENTIC_ID_URL": "https://YOUR_AGENTIC_ID_HOST",
>         "AGENTIC_ID_API_KEY_FILE": "/absolute/path/to/key-file"
>       }
>     }
>   }
> }
> ```

**3. Check the connection**

Ask your agent to call `agentic_id_status`. It reports the server address, the workspace and whether contact values are masked.

## Authentication

The server sends one credential as a Bearer token. It picks the first that exists:

| Order | Credential | How to set it |
| - | - | - |
| 1 | API key | `AGENTIC_ID_API_KEY` in the server's environment, or `AGENTIC_ID_API_KEY_FILE` pointing to a file that holds the key |
| 2 | Sign-in | Call the `agentic_id_login` tool, or run `agentic-id login` in a terminal |

An API key, when set, is used instead of a sign-in.

**Sign-in** is OAuth 2.1 with PKCE. The browser opens the sign-in page, and the session is stored in `~/.agentic-id/session.json`, readable by you only. The access token lasts 1 hour and is renewed with a refresh token that lasts 30 days. `agentic_id_login` with `action: "logout"` ends the session.

> [!WARNING]
>
> Never paste an API key into a chat. Keep it in a file or in your client's secret store. See [API keys](https://docs-agentic-id.icustomer.ai/api-keys.md) and [Authentication](https://docs-agentic-id.icustomer.ai/authentication.md).

### Environment variables

| Variable | Purpose |
| - | - |
| `AGENTIC_ID_URL` | The Agentic ID API address |
| `AGENTIC_ID_API_KEY` | API key |
| `AGENTIC_ID_API_KEY_FILE` | Path of a file that holds the API key |
| `AGENTIC_ID_CONFIG_DIR` | Folder for the session and the usage log. Default `~/.agentic-id` |

## How answers look

Each tool result has a text block (a one-line summary, then the full answer as JSON) and the same answer as structured content.

A failed call is marked `isError` and carries this body:

```json theme={null}
{
  "error": "credits.insufficient",
  "status": 402,
  "message": "Not enough credits for this request: 0 available. Nothing was charged. Add credits, or ask for less.",
  "fix": "The wallet cannot cover this call. Stop and tell the user; do not retry or raise the cap.",
  "request_id": "req_..."
}
```

`"sent": false` means the server refused the call on your machine. Nothing reached Agentic ID and nothing was charged. See [Errors](https://docs-agentic-id.icustomer.ai/errors.md).

Every paid call is sent with an [idempotency key](https://docs-agentic-id.icustomer.ai/idempotency.md), so the server can retry a dropped connection without charging twice.

## Available tools

Fifteen tools. An argument the tool does not have is refused with the list of allowed names.

| Tool | Purpose | Credits |
| - | - | - |
| `agentic_id_validate` | Is this work mailbox real? | 1 per `valid`, `invalid` or `catch-all` answer. `unknown` and `rejected` are not charged. |
| `agentic_id_resolve` | One stable Agentic ID for a person or company | 1 per ID. 0 for an ID your workspace already holds while it contributes. |
| `agentic_id_resolve_many` | Resolve up to 500 rows and group duplicates | 1 per ID returned |
| `agentic_id_enrich` | Fill in missing facts, each with its level | 2 per person, plus 5 when a phone is delivered; 1 per company. Nothing found, nothing charged. |
| `agentic_id_find` | People in a role at one known company | 2 per person delivered |
| `agentic_id_discover` | Companies, and optionally people, that match filters | 1 per account plus 2 per person. `count_only` is not charged. |
| `agentic_id_lookalike` | Companies like your seed companies | 1 per account delivered |
| `agentic_id_facts` | Each fact's level and evidence for one ID | Not charged |
| `agentic_id_ledger` | One ID's history, hash chain re-checked | Not charged |
| `agentic_id_workspace` | Credits, spend and recent charges | Not charged |
| `agentic_id_report` | Report what happened to a value | Not charged |
| `agentic_id_list` | Run one action over a CSV file | As the action. `dry_run` is not charged. |
| `agentic_id_login` | Sign in or sign out | Not charged |
| `agentic_id_estimate` | The most a planned call could cost | Not charged |
| `agentic_id_status` | Check the connection | Not charged |

The `cost` block in each answer is the authority on what was charged. See [Credits](https://docs-agentic-id.icustomer.ai/credits.md).

### Shared parameters

**max\_credits** `integer`

The most the call may charge, 0 to 100000. A call that could cost more than 10 credits is refused without it.

**purpose** `string`

Why you are asking. One of `b2b_outbound`, `ad_audience`, `own_customer_enrichment`, `fraud_check`. Defaults to `b2b_outbound`. See [Data and privacy](https://docs-agentic-id.icustomer.ai/data-privacy.md).

**identifiers** `object`

What you know about the person or company: `email`, `linkedin_url`, `name`, `company_name`, `company_domain`. One strong identifier is enough. A name needs a company or another identifier with it.

### agentic\_id\_validate

| Parameter | Type | Notes |
| - | - | - |
| `email` | string | One work email |
| `emails` | string\[] | Several work emails. Lists over 1,000 are sent in batches inside `max_credits`. Repeats are checked once. |
| `domain` | string | A company domain: is it live and does it take mail |
| `purpose` | string | |
| `max_credits` | integer | |

### agentic\_id\_resolve

| Parameter | Type | Notes |
| - | - | - |
| `identifiers` | object | See shared parameters |
| `email`, `linkedin_url`, `name`, `company_name`, `company_domain`, `domain` | string | The same fields, accepted at the top level |
| `kind` | `person` or `company` | Inferred when omitted: a person if any person field is given |
| `spend` | boolean | Ask paid sources when the ledger cannot resolve it. Default `false`. |
| `purpose` | string | |
| `max_credits` | integer | |

### agentic\_id\_resolve\_many

| Parameter | Type | Notes |
| - | - | - |
| `records` | object\[] | Required. Up to 500 identifier objects, in list order. |
| `kind` | `person` or `company` | |
| `spend` | boolean | |
| `purpose` | string | |
| `max_credits` | integer | |

Rows that resolve to the same ID are grouped in `same_id`.

### agentic\_id\_enrich

| Parameter | Type | Notes |
| - | - | - |
| `contact` | object | One person, as identifiers |
| `contacts` | object\[] | Several people. Lists over 100 are sent in batches inside `max_credits`. |
| `company` | object | `domain`, `name` |
| `fields` | string\[] | Only these fields. People: `work_email`, `linkedin_url`, `title`, `seniority`, `company_name`, `company_domain`, `location`, `city`, `country`. Companies: `name`, `domain`, `linkedin_url`, `industry`, `employees`, `revenue_usd`, `country`, `city`, `founded`, `description`. |
| `purpose` | string | |
| `max_credits` | integer | |

Phone fields are refused.

### agentic\_id\_find

| Parameter | Type | Notes |
| - | - | - |
| `account` | object | Required. `domain` or `id` (the company's Agentic ID). |
| `roles` | string\[] | Job titles, for example `["VP Marketing"]` |
| `seniority` | string or string\[] | For example `"director+"` or `["vp", "c_suite"]` |
| `countries` | string\[] | Where the person is, as ISO codes |
| `limit` | integer | 1 to 25. Default 5. |
| `exclude_seen` | boolean | Skip people already delivered to this workspace. Default `true`. |
| `purpose` | string | |
| `max_credits` | integer | |

A search needs `roles` or `seniority`.

### agentic\_id\_discover

| Parameter | Type | Notes |
| - | - | - |
| `account_filters` | object | `industry` (string\[]), `country` (string\[], ISO codes), `employees_min`, `employees_max`, `technologies` (string\[]), `keywords` (string\[]), `keywords_required` (boolean) |
| `contact_filters` | object | `job_title` (string\[]), `job_level` (string or string\[]), `countries` (string\[]), `per_account` (1 to 10), `min_company_size` |
| `max_accounts` | integer | 1 to 500. Default 25. |
| `exclude_seen` | boolean | Default `true` |
| `count_only` | boolean | How many match. Nothing is delivered and nothing is charged. |
| `purpose` | string | |
| `max_credits` | integer | |

Keywords rank results. They filter only with `keywords_required`.

### agentic\_id\_lookalike

| Parameter | Type | Notes |
| - | - | - |
| `seeds` | string\[] | Required. 1 to 50 company domains. |
| `max_accounts` | integer | 1 to 500. Default 25. |
| `exclude_seen` | boolean | |
| `purpose` | string | |
| `max_credits` | integer | |

### agentic\_id\_facts and agentic\_id\_ledger

| Parameter | Type | Notes |
| - | - | - |
| `id` | string | Required. An Agentic ID (`ic-...`). |

### agentic\_id\_workspace

| Parameter | Type | Notes |
| - | - | - |
| `recent` | integer | 0 to 200. How many of the latest grants and charges to list. Default 10. |

### agentic\_id\_report

| Parameter | Type | Notes |
| - | - | - |
| `id` | string | The Agentic ID the value belongs to. Your workspace must hold it. |
| `field` | `work_email`, `title` or `company_domain` | Default `work_email` |
| `outcome` | `bounced`, `replied`, `wrong_person` or `confirmed` | |
| `reports` | object\[] | Up to 200 reports in one call, each with `id`, `outcome` and optionally `field`. Use in place of `id`, `field`, `outcome`. |

### agentic\_id\_list

| Parameter | Type | Notes |
| - | - | - |
| `action` | `validate`, `resolve`, `enrich` or `report` | Required |
| `file` | string | Required. Full path of the CSV file. |
| `out` | string | Where to write the result. Default: next to the input, named `<name>.agentic-id.csv`. |
| `replace_original` | boolean | Save the original as `<name>.original.csv`, then put the result in its place |
| `dry_run` | boolean | Count the rows and estimate the cost. Nothing is sent. |
| `max_credits` | integer | |
| `fields` | string\[] | `enrich` only |
| `column` | string | The email column, when its name is not recognised |
| `columns` | object | Column names: `email`, `linkedin`, `name`, `company`, `domain` |
| `limit_rows` | integer | Only the first N rows |
| `field` | string | `report` only: the field every outcome is about |
| `purpose` | string | |

The rows are read and written by the server and do not enter the conversation.

### agentic\_id\_login

| Parameter | Type | Notes |
| - | - | - |
| `action` | `login` or `logout` | Default `login` |

Returns a sign-in link at once. Call it again after signing in to confirm.

### agentic\_id\_estimate

| Parameter | Type | Notes |
| - | - | - |
| `tool` | string | Required. One of `validate`, `resolve`, `resolve_many`, `enrich`, `find`, `discover`, `lookalike`. |
| `arguments` | object | The arguments you would pass |

Worked out on your machine. Nothing is sent.

### agentic\_id\_status

No parameters.

## What the server tells agents about spending

The server sends instructions to the agent when it connects. On spending they say:

* These calls are not charged: status, workspace, facts, ledger, estimate, report, login, discover with `count_only`, list with `dry_run`. Every other call costs credits.
* Before any call that could cost more than 10 credits, the user must have stated a number of credits. "Go ahead" is not a budget. The agent shows the arithmetic (an estimate or a count) and asks for a number.
* The agent never picks `max_credits` above what the user said. If the user gave a budget, it is used without asking again.
* `max_credits` is set on every paid call. Afterwards the agent says what was charged, from `cost.charged_credits`.
* For "what did I spend", the agent calls `agentic_id_workspace`. That is the billing record.

The server enforces the 10-credit rule itself: a call whose worst case is above 10 credits and has no `max_credits` is refused with `cap_required` and the estimate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.