# @deepidv/mcp-server

npm wrapper for **deepidv's hosted MCP server** — identity verification, KYC/KYB, PEP & sanctions screening, bank statement analysis, and workflow automation, exposed to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io).

> deepidv's MCP server is a **remote, hosted service** at `https://mcp.deepidv.com/v1/mcp`. This package does not run a local server — it bridges stdio-based MCP clients to that hosted endpoint (via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)) and handles the OAuth 2.0 Authorization Code + PKCE flow. Use this package only if your MCP client requires a local/package-installed server rather than a direct remote HTTP connection.

If your client supports remote MCP servers natively (Claude Desktop, Claude Code, Cursor, etc.), skip this package and connect directly to `https://mcp.deepidv.com/v1/mcp` instead — see [Direct connection](#direct-connection-recommended) below.

## Installation

```bash
npx -y @deepidv/mcp-server
```

Or install globally:

```bash
npm install -g @deepidv/mcp-server
deepidv-mcp
```

## Usage in an MCP client config

```json
{
  "mcpServers": {
    "deepidv": {
      "command": "npx",
      "args": ["-y", "@deepidv/mcp-server"]
    }
  }
}
```

On first run, a browser window will open for you to sign in with your deepidv email and password (plus MFA if enabled on your account). No `client_id` or `client_secret` configuration is required — this package uses deepidv's shared public OAuth client (`deepidv`) with PKCE.

The wrapper checks callback port `3335` before starting. If it is busy, it automatically selects another available localhost port and updates the OAuth callback metadata for that run. To request a different preferred port, set `DEEPIDV_MCP_CALLBACK_PORT` to a value between `1` and `65535`.

If a previous interrupted login left stale OAuth state, remove the local `.mcp-auth` directory and start again:

```bash
rm -rf ~/.mcp-auth
```

On Windows PowerShell:

```powershell
Remove-Item -Recurse -Force "$HOME\.mcp-auth"
```

## Direct connection (recommended)

Most modern MCP clients support remote HTTP servers natively and don't need this package at all. Add the server directly:

```json
{
  "mcpServers": {
    "deepidv": {
      "url": "https://mcp.deepidv.com/v1/mcp",
      "transport": "http"
    }
  }
}
```

See the full setup guide: https://github.com/Deep-Identity-Inc/agent-skills/tree/main/mcp-server

## Requirements

- Node.js >= 18
- An active deepidv account
- An MCP client that can either run local packages (`npx`) or connect to remote HTTP servers with OAuth 2.0 Authorization Code + PKCE

## What you can do once connected

- Search applicants and check invitation status
- List, inspect, create, and manage verification sessions
- Create and reuse workflows built from deepidv verification steps
- List bank statement records and send bank statement requests
- Run PEP/sanctions, title-check, and adverse-media screening

Full tool reference: https://github.com/Deep-Identity-Inc/agent-skills/tree/main/mcp-server#available-tools

## Security

- All requests are authenticated via OAuth 2.0 Authorization Code + PKCE (S256) — there is no unauthenticated access
- No client secret is stored or transmitted by this package
- Access is scoped to the authenticated deepidv user and organization

## Support

https://www.deepidv.com/support

## License

MIT