> For the complete documentation index, see [llms.txt](https://docs.compliance.phalcon.blocksec.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.compliance.phalcon.blocksec.com/integrations/mcp-server.md).

# MCP Server

This guide explains how to connect Phalcon Compliance to an AI assistant using the Model Context Protocol (MCP). Once connected, you can screen addresses and transactions, and read existing screening results, directly in a conversation with your assistant — without switching to the Phalcon Compliance dashboard.

Phalcon Compliance identifies and reports AML risk. It does not act on it: the MCP server is read-and-screen only and cannot change anything in your account.

## Prerequisites

* An active Phalcon Compliance account. Available on all plans.
* An AI assistant that supports remote MCP servers.

## Connect your assistant

Phalcon Compliance hosts the MCP server. Nothing to install, and it stays up to date automatically.

Add the following server URL wherever your assistant manages MCP servers or connectors:

```
https://mcp.blocksec.com/mcp
```

The first time your assistant calls Phalcon Compliance, your browser opens an authorization page:

1. Sign in to Phalcon Compliance, or create an account.
2. Review what you are granting: where you will be sent back to, the account and organization the connection will use, and what it will be able to do. If you are asked to confirm that you recognize the return address, do so — you cannot continue otherwise.
3. Select **Authorize**.

Your assistant is connected. You are not asked to authorize again unless the connection is removed or expires.

<figure><img src="https://1419887533-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPfx6yOSRmp0GCnHv5rhy%2Fuploads%2Fgit-blob-cfc1fdc28aa022afb5ad95e1252142d7ed892277%2Fmcp-server-authorization.png?alt=media" alt="The Phalcon Compliance authorization page, showing where you will be sent back to, the account and organization the connection will use, a checkbox confirming you recognize the return address, and what the connection will be able to do"><figcaption><p>The authorization page shows the account and organization the connection will use, and what it will be able to do.</p></figcaption></figure>

### Setup for specific assistants

Follow the instructions for your assistant below. Claude Code, Codex, and Cursor require the client ID shown in their configuration, in addition to the server URL. Copy the value exactly: it identifies the assistant, not your Phalcon Compliance account, and is not an API key. Do not append it to the server URL.

For an assistant not listed here, contact <phalcon_support@blocksec.com> for connection instructions.

#### Claude

Go to **Customize → Connectors**, select **+**, then **Add custom connector**, and paste the server URL.

On Team and Enterprise plans, an owner adds the connector once under **Organization Settings → Connectors**. Members then connect to it individually.

#### Claude Code

```bash
claude mcp add --scope user --transport http \
  --client-id https://claude.ai/oauth/claude-code-client-metadata \
  phalcon-compliance https://mcp.blocksec.com/mcp
```

`--scope user` makes the server available in every project. Without it, it is added only to the project you are currently in.

#### Codex

```bash
codex mcp add phalcon-compliance \
  --url https://mcp.blocksec.com/mcp \
  --oauth-client-id https://chatgpt.com/oauth/codex/client.json
```

The server is written to `~/.codex/config.toml`, which the Codex CLI, the IDE extension, and the desktop app all read. Adding it once covers all three.

#### Cursor

Add the server to your `mcp.json`:

```json
{
  "mcpServers": {
    "Phalcon Compliance": {
      "url": "https://mcp.blocksec.com/mcp",
      "auth": {
        "CLIENT_ID": "https://cursor.com"
      }
    }
  }
}
```

`CLIENT_ID` identifies Cursor itself, not your account. Copy it exactly as shown.

#### VS Code (GitHub Copilot)

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "phalcon-compliance": {
      "type": "http",
      "url": "https://mcp.blocksec.com/mcp"
    }
  }
}
```

The top-level key is `servers`, not `mcpServers`. Reload the window afterwards, then switch Copilot Chat to **Agent** mode — MCP tools are only available there.

#### ChatGPT

Custom MCP servers require Developer Mode and a paid ChatGPT plan, and work on the web only. On Business, Enterprise, and Edu workspaces, an administrator enables custom MCP before anyone can add one.

Follow OpenAI's instructions for [enabling Developer Mode and adding a custom connector](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt), and use the server URL above. Leave authentication set to OAuth.

## What your assistant can do

Ask in plain language — your assistant selects the right action.

| You can ask for                            | Uses screening quota           |
| ------------------------------------------ | ------------------------------ |
| Screening an address for AML risk          | Yes — 1 screening              |
| Screening a transfer inside a transaction  | Yes — 1 screening per transfer |
| The latest screening result for an address | No                             |
| The list of transfers in a transaction     | No                             |
| The latest screening result for a transfer | No                             |
| The result of a queued screening           | No                             |
| Your screening usage over a period         | No                             |
| The list of supported chains               | No                             |

On **Scale and Enterprise** plans, your assistant can also submit batches — up to 100 addresses or 50 transactions per request. Each item in a batch consumes one screening.

Every screening result includes a link to the matching record in the Phalcon Compliance dashboard.

{% hint style="warning" %}
Screening results are a snapshot from the moment the screening ran, and your assistant may summarize or paraphrase them. Open the linked dashboard record before making a compliance decision.
{% endhint %}

### Choosing a chain

The same address or transaction hash can exist on more than one chain. If you do not say which chain you mean, your assistant asks before screening — unless the format identifies a single chain on its own, as Bitcoin, Tron, and Solana addresses do. Answering that question consumes no quota.

Results name the chain they cover. Check that it is the one you meant before acting on them.

### Screening a transaction

Screening works at the transfer level, not the transaction level. A transaction holding five transfers takes five screenings to cover completely.

If a transaction contains more than one transfer, your assistant asks which one you mean before screening — usually by asking for the address that received the funds. Answering that question is a normal step, not an error, and no quota is consumed until the transfer is identified.

By default, a screening covers both where the funds came from and where they went. Ask your assistant to narrow it to one side if you only need one direction. Either way it costs one screening.

### Risk levels

Risk levels come from your own Risk Engine rules, not from a fixed scale. Each finding carries the severity you set for the rule that produced it, and the overall level is simply the highest of those. The same address can come back at a different level for another organization.

Two things follow from that:

* Because the overall level is the highest single finding, ask your assistant which finding drove it.
* **No Risk** means nothing matched your rules. It is not a statement that the address or transfer is clean.

Ask your assistant for the evidence behind a level — the indicator that fired, the amounts, how many events matched — rather than relying on the level alone.

Rules are configured in the Phalcon Compliance dashboard and are available on Essential plans and above. They cannot be changed through an assistant.

## Screening quota

Screenings through your assistant draw on the same quota as the dashboard and the API. There is no separate allowance.

Reading existing results never consumes quota. If a recent result already exists, your assistant can read that instead of running a new screening. Ask it to re-screen when you need the current state — that runs a new screening and uses one from your quota.

When your quota runs out, your assistant tells you and links to the billing page. To check your usage at any time, ask your assistant for your screening usage, or open the dashboard.

## Permissions

The connection has exactly the permissions you have in the Phalcon Compliance dashboard — no more, no less.

If your role in the organization is view-only, your assistant can read existing screening results but cannot run new screenings. Ask an organization admin for access if you need to run them.

An assistant can also request read-only access for itself. What a connection is able to do is listed on the authorization page before you select **Authorize**.

## Organization

The connection is bound to a single organization: the one you were most recently using when you authorized it. The organization is shown on the authorization page before you select **Authorize**.

To use a different organization, disconnect and connect again while that organization is active.

## Disconnect

Remove the Phalcon Compliance server from your assistant's MCP or connector settings. Assistants that support OAuth token revocation also revoke the access token at that point.

If you need confirmation that access has ended, contact ***<phalcon_support@blocksec.com>***.

## Limitations

* **Read and screen only.** The connection cannot add or remove blacklist and whitelist entries, edit customers, start or stop monitoring, or act on alerts and cases.
* **Monitoring, Alert Hub, Customer Management, and Risk Engine configuration** are not available through an assistant. Use the dashboard or the API for those.
* Batch submission requires a Scale or Enterprise plan.

## Next Steps

* [Address Screening](https://docs.compliance.phalcon.blocksec.com/manual/screening/addresses.md): screening addresses in the dashboard.
* [Transaction Screening](https://docs.compliance.phalcon.blocksec.com/manual/screening/transactions.md): how transfer-level screening works.
* [Plans, Billing, and Payment](https://docs.compliance.phalcon.blocksec.com/manual/account/plans-billing-and-payment.md): quota and plan limits.
* [API Documentation](https://docs.compliance.phalcon.blocksec.com/api-documentation/introduction.md): the underlying REST API.
