Trustfull MCP

Pick your client below, run one command, sign in with your Trustfull account, and your agent can score phone numbers, email addresses and IP addresses inside the conversation over the Model Context Protocol.

Test the connection

After you set up your client, check that the connection works.

1. Health check — confirm the server answers:

curl https://mcp.trustfull.com/status

Expected response:

{"scope": "status_check", "status": "ok"}

2. List tools — ask your AI agent to list the available Trustfull tools. You should see all five tools from the Available tools section.

3. Run a test query — try "Score the phone number +1234567890". If the connection works, the agent calls the score_phone tool and returns the result.

Available tools

Your AI agent discovers these tools and calls them when the conversation needs them.

Risk scoring

Reference data

All tools are read-only. Each scoring call spends one credit of the API Key you selected at sign-in.

Example prompts

Once your client is connected, try prompts like these:

• Phone scoring: "Check the phone number +39 349 551 6028 for fraud risk"
• Email scoring: "Score the email address [email protected] and explain the risk signals"
• IP scoring: "Evaluate the IP address 185.220.101.34 and tell me if it looks suspicious"
• Batch analysis: "Score these three phone numbers and compare their risk levels: +1 555 0100, +44 7911 123456, +49 170 1234567"
• Investigation: "I received a signup from email [email protected] and IP 103.21.244.0. Score both and give me a summary of the risk"
• Reason codes: "What do the reason codes PHONE_CARRIER_VOIP and PHONE_LINE_TYPE_MOBILE mean?"

The agent calls the right tool and presents the result in a readable format.

Understanding the response

Each scoring tool returns three sections:

1. data — the full scoring result, identical to the matching REST API response. It carries the numeric score, the label, and every supporting signal.
2. llm_consumer_instruction — formatting guidelines that help the agent present the result clearly.
3. reason_codes_catalog — the entries of the reason codes catalog that the result cites, so the agent can explain the risk and trust signals without a second lookup.

The agent therefore has everything it needs to explain the result, not only to repeat it.

Why use the MCP server?

If you already call the REST APIs, here is what the MCP server adds:

• Natural language interface — ask for a score in plain language, with no API call to write.
• Built-in context — every response carries the reason codes and the formatting instructions.
• No integration code — connect an existing AI tool in minutes, with no backend to maintain.
• Data where you work — in a support ticket, a transaction review, or an agent you are building.

The Model Context Protocol is an open standard that connects AI models to external tools. The agent discovers the tools from the server, understands what they do, and calls them when the conversation needs them.

Security considerations

Human in the loop

• Most clients ask you to confirm each tool call. Keep that confirmation on, above all with production keys.
• For an autonomous agent that calls tools without confirmation, scope its access and validate the inputs first.

Prompt injection

• Untrusted user content can try to steer the agent into unintended tool calls. This is a general risk with LLM tool integrations, not a Trustfull specific one.
• Validate and sanitize user input before it reaches the agent, above all in automated pipelines.

Data privacy

• The server keeps no data beyond what the request needs. Scoring results are not retained after the response goes out.
• All traffic uses HTTPS (TLS 1.2 or later).

Troubleshooting

The agent does not see the Trustfull tools

• Restart the client after you add the MCP configuration.
• Check the server URL: https://mcp.trustfull.com/connector/, with the trailing slash.
• Run the health check to confirm the server answers from your network.

The tool call returns an authentication error

• Sign in again from your client: run /mcp in Claude Code, or codex mcp login trustfull in Codex.
• Check that the API Key you selected is still active in your Trustfull dashboard.

The tool call times out

• Tool calls time out after 30 seconds. Delays upstream can reach that limit.
• Retry the request. If it continues, check the status page or click Ask AI in the dashboard header.

The response is empty or unexpected

• Check the input format. Phone numbers go in international format, such as +391234567890. Email addresses and IP addresses must be valid.
• Read result.content[0].text in the JSON-RPC response for the error detail.

Connection refused, or an SSL error

• Allow outbound HTTPS to mcp.trustfull.com on port 443.
• Behind a corporate proxy or firewall, add the domain to the allow list.

Claude connector

The Trustfull connector for Claude lets Claude score phone numbers, email addresses and IP addresses with your Trustfull account, inside the conversation. You sign in with your Trustfull dashboard credentials and choose the API Key Claude may use. The key stays with Trustfull.

Use it from Claude.ai and Claude Desktop.

Before you start

You need:

• A Trustfull dashboard account: the email and password you use at dashboard.trustfull.com.
• At least one active API Key with credits on that account. If you do not have one yet, click Ask AI in the dashboard header and ask for one. See Getting Support.
• A Claude plan that supports connectors. On Team and Enterprise plans an administrator enables the connector for the organization before members can connect.

Connect from Claude.ai or Claude Desktop

Claude Desktop shares its connectors with Claude.ai: connect once and use it in both.

1. Open Settings → Connectors and click Browse connectors.
2. Find Trustfull in the directory and click Connect. On Team and Enterprise plans an administrator enables Trustfull for the organization first, from the admin settings. Members then find it in their own connectors list.
3. A Trustfull window opens. Sign in with your dashboard credentials if you are not signed in already.
4. On the consent screen, select the API Key Claude may use, review the details and click Allow.
5. Claude takes you back. The Trustfull tools are on in each new conversation, and you can switch them off per conversation from the tools menu.

The consent screen

• API Key: the key Claude will use. Trustfull bills each score Claude runs to this key and lists it in your dashboard like any other API call, with a customer_id that starts with mcp-.
• Details: the name and website of the application that asks for access, the address it returns to, and the tools it gets.
• Allow creates the connection. Cancel returns to Claude without granting anything.

Claude receives a token that stands for your choice, and Trustfull swaps it for the key on each call.

Available Tools

The connector exposes the five tools described above. There is no API key parameter: the key comes from the sign-in.

Risk Scoring

Reference Data

Each scoring tool checks its input before it calls Trustfull. If the value is not a phone number, an email address or an IP address, the tool refuses it, tells you what to send instead and spends no credit. A successful result contains the full API response, formatting guidance for the model, and the entries of the Reason Codes catalog that the result cites.

Example Prompts

You do not type the API key in the prompt: the connection carries it.

• Phone scoring: "Check the phone number +39 349 551 6028 for fraud risk"
• Email scoring: "Score [email protected] and explain the risk signals"
• IP scoring: "Is 185.220.101.34 a proxy or a VPN?"
• Investigation: "I received a signup from [email protected] and IP 103.21.244.0. Score both and summarize the risk"
• Documentation: "What does the field email_domain_age mean?" or "List the reason codes of the phone product"

Sessions, Expiry and Disconnecting

• Claude receives an access token that is valid for 1 hour and refreshes it on its own.
• The connection itself lasts 30 days. After that Claude asks you to sign in again. Refreshing does not extend the 30 days.
• To disconnect, remove the connector in Claude (Settings → Connectors → Trustfull). Claude stops calling Trustfull at once. On Trustfull's side the connection expires within its 30 days.
• To cut access at once, have the API Key you selected rotated: click Ask AI in the dashboard header. The connection uses that key on each call, so the tools stop working the moment the key changes.

What Trustfull Stores

• Who connected (the email of the dashboard user and the company), which API Key you selected, and hashes of the tokens. Trustfull keeps this record for the 30 days of the connection.
• The scores Claude asks for are ordinary API lookups: they appear in your dashboard and follow the same retention as any other lookup, described in the Privacy Policy.
• Trustfull receives only the value to score: the phone number, the email address or the IP address. The rest of your conversation with Claude does not reach Trustfull.

Troubleshooting

Claude cannot connect

• Make sure your account has at least one API Key: you cannot complete the consent screen without one.

Claude asks me to sign in again

• The connection lasts 30 days. Signing in again renews it for another 30 days.
• Someone may have removed the API Key you selected from your account. Select another one.

A tool answers "is not a phone number", "is not an email address" or "is not an IPv4 or IPv6 address"

• The tool checks the input before it sends it. Phone numbers work best in international format, for example +391234567890. An email address needs a name and a domain, an IP address must be a valid IPv4 or IPv6 address.

A tool answers with a Trustfull error

• The message is the one the Trustfull API returned. An exhausted credit balance or a disabled API Key are the usual causes: check the key in your dashboard.

A tool times out

• Tool calls have a 30-second limit. Retry. If the problem persists, check the Trustfull status page or click Ask AI in the dashboard header.

FAQ

Can I use the connector with more than one API Key?

A connection uses one key. To switch, disconnect the connector in Claude and connect again, choosing another key on the consent screen.

Do my teammates share my connection?

No. Each Claude user connects with their own Trustfull login and chooses their own API Key. On Team and Enterprise plans the administrator enables the connector, then each member connects on their own.

Are there rate limits?

The server applies a rate limit of 5 requests per second. For higher throughput, click Ask AI in the dashboard header. See Getting Support.

FAQ