MCP Server

The Trustfull MCP Server enables AI assistants and LLM-powered applications to access Trustfull's risk scoring capabilities through the Model Context Protocol (MCP). By connecting your AI agent to our MCP Server, it can score phone numbers, email addresses, and IP addresses in real time, directly within the conversation flow.

This integration is ideal for building AI-powered fraud prevention workflows, automated risk assessment agents, and intelligent customer verification systems.

Why Use the MCP Server?

If you are already using Trustfull's REST APIs, you might wonder what the MCP Server adds. Here is what makes it different:

• Natural language interface — Your AI agent can score a phone number or email just by being asked in plain language. No need to write API calls manually.
• Built-in context — Each response includes reason codes and formatting instructions, so the AI agent can interpret and explain the results without additional lookups.
• No integration code — Connect your existing AI tools (Claude, Cursor, VS Code, ChatGPT) to Trustfull in minutes, with no backend code to write or maintain.
• Real-time data in your workflow — Whether you are reviewing a support ticket, investigating a transaction, or building an agent, Trustfull data is available right where you work.

What is MCP?

The Model Context Protocol is an open standard that allows AI models to interact with external tools and data sources. Instead of calling REST APIs directly, the AI agent discovers available tools from the MCP server, understands their purpose, and calls them as needed during a conversation.

Trustfull's MCP Server is hosted and fully managed. There is nothing to install or deploy on your side.

Server URL

https://mcp.trustfull.com/mcp/

Authentication

The MCP Server itself does not require separate authentication. Instead, your Trustfull API key is passed as a parameter in each tool call that queries the scoring APIs. This is the same API key you use for the standard API Integration.

If you do not have an API key yet, contact [email protected] to get started.

Available Tools

The MCP Server exposes the following tools that your AI agent can discover and use:

Risk Scoring

Reference Data

Each scoring tool returns the full API response along with reason codes and formatting instructions, so the AI agent can interpret and present the results naturally.

All tools are read-only, idempotent, and safe to call at any time.

Example Prompts

Once you have connected your AI client to the Trustfull MCP Server, you can try prompts like these:

• Phone scoring: "Check the phone number +39 349 551 6028 for fraud risk using my API key FIDO-XXY"
• 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 AI agent will automatically call the appropriate tools and present the results in a clear, readable format.

Supported Clients

The Trustfull MCP Server works with any MCP-compatible client. Below are setup instructions for the most popular platforms.

Claude Desktop

To connect Claude Desktop to the Trustfull MCP Server, add the following configuration to your Claude Desktop settings file.

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trustfull": {
      "type": "streamable-http",
      "url": "https://mcp.trustfull.com/mcp/"
    }
  }
}

After saving the file, restart Claude Desktop. You should see the Trustfull tools listed in the tools menu. When you ask Claude to score a phone number or email, it will call the appropriate tool and present the results.

Claude will ask you to confirm each tool call before executing it. You can review the parameters (including the API key) before approving.

Claude Code

To use the Trustfull MCP Server with Claude Code, add the server configuration using the CLI:

claude mcp add trustfull --transport streamable-http https://mcp.trustfull.com/mcp/

Once added, Claude Code will automatically discover the available tools and use them when relevant to your conversation.

ChatGPT

To connect ChatGPT to the Trustfull MCP Server:

1. Open ChatGPT Settings and navigate to the Tools section
2. Click Add Tool and select MCP
3. Enter the server URL: https://mcp.trustfull.com/mcp/
4. Save and start a new conversation

ChatGPT will discover the available Trustfull tools and use them when you ask it to score a phone number, email, or IP address.

Cursor

To connect Cursor to the Trustfull MCP Server, open your Cursor settings and navigate to the MCP section, or add the following to your .cursor/mcp.json file:

{
  "mcpServers": {
    "trustfull": {
      "type": "streamable-http",
      "url": "https://mcp.trustfull.com/mcp/"
    }
  }
}

Restart Cursor after saving. The Trustfull tools will be available to the AI agent within your editor.

VS Code / GitHub Copilot

To use the Trustfull MCP Server with VS Code and GitHub Copilot, add the following to your .vscode/mcp.json file in your workspace (or to your user settings):

{
  "servers": {
    "trustfull": {
      "type": "http",
      "url": "https://mcp.trustfull.com/mcp/"
    }
  }
}

After saving, open the Copilot Chat panel. The Trustfull tools will appear in the agent mode tool list.

Windsurf

To connect Windsurf to the Trustfull MCP Server, open your Windsurf settings and add the following MCP server configuration:

{
  "mcpServers": {
    "trustfull": {
      "type": "streamable-http",
      "serverUrl": "https://mcp.trustfull.com/mcp/"
    }
  }
}

Restart Windsurf after saving. The Trustfull tools will be available to Cascade.

OpenAI Agents SDK

OpenAI models can connect to MCP servers using the Responses API. To use Trustfull's MCP Server, include it as a tool in your API request:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "trustfull",
            "server_url": "https://mcp.trustfull.com/mcp/",
            "require_approval": "always",
        }
    ],
    input="Score the phone number +1234567890 using API key YOUR_API_KEY",
)

print(response.output_text)

When using the OpenAI integration, your API key is passed as a tool parameter within the prompt. Make sure your application handles it securely and does not expose it to end users.

Custom Clients (HTTP)

If you are building a custom MCP client or want to interact with the server directly, you can use the standard MCP protocol over HTTP with Server-Sent Events.

1. Initialize the session

Send a handshake request to establish a session:

curl -X POST https://mcp.trustfull.com/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {"tools": {}},
      "clientInfo": {"name": "my-client", "version": "1.0"}
    }
  }'

The response includes a Mcp-Session-Id header. Save this value and include it in all subsequent requests.

2. Send the initialization notification

curl -X POST https://mcp.trustfull.com/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

3. Discover available tools

curl -X POST https://mcp.trustfull.com/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

4. Call a tool

curl -X POST https://mcp.trustfull.com/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "score_phone",
      "arguments": {
        "phone": "+1234567890",
        "api_key": "YOUR_API_KEY"
      }
    }
  }'

The response is delivered as a Server-Sent Events stream. Each event contains a JSON-RPC response with the tool result in result.content[0].text.

Replace SESSION_ID with the value from the Mcp-Session-Id header received in step 1. Replace YOUR_API_KEY with your Trustfull API key.

Test the Connection

After setting up your client, verify that the connection is working correctly:

1. Health check — Call the status endpoint to confirm the server is reachable:

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 described in the Available Tools section above.

3. Run a test query — Try a simple prompt such as "Score the phone number +1234567890 using API key YOUR_API_KEY". If the connection is working, the agent will call the score_phone tool and return the scoring result.

Understanding the Response

When you call a scoring tool (score_phone, score_email, or score_ip), the response contains three sections:

1. data: The full scoring result, identical to what you would receive from the corresponding REST API. This includes the numeric score, label, and all supporting signals.
2. llm_consumer_instruction: Formatting guidelines that help the AI agent present the results in a clear and readable way.
3. reason_codes_catalog: The full list of reason codes, enabling the AI agent to interpret and explain the risk and trust signals in the response.

This means the AI agent has everything it needs to not only return the raw data, but also explain the results in natural language.

Security Considerations

When using the MCP Server, keep the following security practices in mind:

API Key Handling

• Your Trustfull API key is passed as a parameter in each tool call. Make sure it is not hardcoded in prompts that are visible to end users.
• In agentic applications, store the API key server-side and inject it into the tool call at runtime, rather than including it in the user-facing prompt.
• If you suspect your API key has been compromised, contact [email protected] to rotate it immediately.

Human-in-the-Loop

• Most MCP clients (Claude Desktop, Cursor, VS Code) prompt you to confirm each tool call before execution. We recommend keeping this confirmation enabled, especially when working with production API keys.
• If you are building an autonomous agent that calls tools without human confirmation, ensure that the agent's access is scoped appropriately and that inputs are validated before being passed to the MCP Server.

Prompt Injection

• When processing untrusted user input, be aware that malicious content could attempt to manipulate the AI agent into making unintended tool calls. This is a general risk with any LLM tool integration, not specific to Trustfull.
• Validate and sanitize user inputs before passing them to the AI agent, especially in automated pipelines.

Data Privacy

• The MCP Server does not store or log the data you send beyond what is necessary to process the request. Scoring results are not retained after the response is delivered.
• All communication with the MCP Server takes place over HTTPS (TLS 1.2+).

Troubleshooting

The AI agent does not see the Trustfull tools

• Make sure you restarted your client after adding the MCP configuration.
• Verify that the server URL is correct: https://mcp.trustfull.com/mcp/ (the trailing slash is required).
• Run the health check to confirm the server is reachable from your network.

Tool call returns an authentication error

• Verify that you are passing a valid Trustfull API key in the api_key parameter.
• Make sure the API key is active and has not been revoked. You can check this in your Trustfull dashboard.

Tool call times out

• The MCP Server has a 30-second timeout for tool calls. If the upstream Trustfull API is experiencing delays, the call may time out.
• Retry the request. If the issue persists, check the Trustfull status page or contact [email protected].

Unexpected or empty response

• Ensure the input format is correct. Phone numbers should be in international format (e.g., +391234567890). Email addresses should be valid. IP addresses should be in IPv4 or IPv6 format.
• Check the result.content[0].text field in the JSON-RPC response for error details.

Connection refused or SSL error

• Make sure your network allows outbound HTTPS connections to mcp.trustfull.com on port 443.
• If you are behind a corporate proxy or firewall, you may need to whitelist the domain.

FAQ

Can I use the MCP Server with other AI platforms?

Yes. Any MCP-compatible client can connect to Trustfull's MCP Server. The integration follows the open MCP standard, so it works with any platform that supports the protocol. If your platform is not listed in the Supported Clients section, refer to its documentation for how to add a remote MCP server.

Is the MCP Server available in the sandbox environment?

Yes. You can use the API Sandbox by passing sandbox-mode parameters through the tool calls.

What happens if a tool call fails?

The server returns a standard JSON-RPC error response with a descriptive message. Common causes include an invalid API key, a malformed input, or a temporary upstream issue. Your AI agent can interpret the error and retry or inform the user accordingly. See the Troubleshooting section for common issues.

Are there rate limits?

The MCP Server applies rate limiting of 5 requests per second. For higher throughput requirements, contact [email protected].

Can I use this in an autonomous agent without human confirmation?

Yes, but we recommend implementing proper input validation and access controls. See the Security Considerations section for best practices when building autonomous workflows.