Connect through MCP

Connect your AI client to ShieldLabs through the Model Context Protocol (MCP). The client discovers the available tools and can use them to investigate identifications, read history and explain risk. You can also manage domains and webhook endpoints. MCP works with results from your browser integration. Keep the snippet or browser SDK installed on the site you protect.

Connect to ShieldLabs

Open MCP setup

Sign in to the analytics dashboard and open Integration > MCP. Choose your client and copy its connection settings. Use the Server URL displayed there.The server endpoint is:

https://mcp.shieldlabs.ai/mcp

Add the server to your AI client

Use the configuration for your client below. A client must support a remote MCP server over Streamable HTTP and OAuth authentication.

When your client opens the ShieldLabs sign-in flow, sign in with the account you want to connect and review the authorization screen. Your client completes OAuth and manages its tokens. Do not paste your ShieldLabs password or API keys into the conversation.

Check the connection

Ask the assistant to run shieldlabs_check_connection. A successful response contains connected: true. Then inspect the client’s tool list to see which operations it exposes.When shieldlabs_list_domains is listed, use it to select the domain for your investigation. Specify the domain hostname on history reads when your account has more than one enabled domain. Domain-management and webhook-management tools use the domain and webhook IDs returned by their list tools.

Client configuration

Codex
Claude Code
Cursor
VS Code
ChatGPT and Claude

Add a remote MCP server in your client’s MCP settings, or use the CLI:

codex mcp add shieldlabs --url https://mcp.shieldlabs.ai/mcp
codex mcp login shieldlabs

claude mcp add --transport http shieldlabs https://mcp.shieldlabs.ai/mcp

Open /mcp, choose ShieldLabs and complete authentication.

Add the server in MCP settings, or save this in .cursor/mcp.json:

{
  "mcpServers": {
    "shieldlabs": { "url": "https://mcp.shieldlabs.ai/mcp" }
  }
}

Complete the sign-in flow when prompted.

Save this in .vscode/mcp.json and start the server from the MCP controls:

{
  "servers": {
    "shieldlabs": {
      "type": "http",
      "url": "https://mcp.shieldlabs.ai/mcp"
    }
  }
}

Complete the sign-in flow when prompted.

Investigation tools

These tools read or analyze identifications. Use the tool list from your connection to confirm availability and the exact input fields.

Tool	What it does
`shieldlabs_check_connection`	Confirms that the connection is authenticated
`shieldlabs_get_identification`	Retrieves one check by Identification ID; can wait for a newly started check
`shieldlabs_search_history`	Searches stored identifications by a supported identifier, with pagination
`shieldlabs_summarize_entity`	Summarizes the returned history for an account, device, visitor, cookie or IP
`shieldlabs_explain_risk_score`	Explains an identification’s score, available contributions and detection flags

A history summary describes the records returned by that query. Its highest score or worst risk band is separate from the analytics dashboard’s current risk category. A missing result means unverified; handle pending or unavailable results explicitly. For the full weighted explanation, provide the scored webhook or its data object to the explanation tool. A History lookup supplies only the fields stored in History; it does not recreate the webhook’s signals array. See Response contracts. Try prompts such as:

For example.com, review Identification ID <IDENTIFICATION_ID>.
Explain the returned score and detections. If no result is available, say so.

For example.com, investigate User HID <USER_HID>.
Summarize the returned history, related devices and public IPs.
State the period and any limits of the returned records.

Domain and webhook tools

Management tools let your assistant prepare the same integrations you manage in the analytics dashboard:

Task	Tools
Read domains	`shieldlabs_list_domains`, `shieldlabs_get_domain`
Add or update a domain	`shieldlabs_add_domain`, `shieldlabs_patch_domain`
Remove a domain or rotate its server key	`shieldlabs_delete_domain`, `shieldlabs_rotate_server_key`
Read endpoints	`shieldlabs_list_webhooks`, `shieldlabs_get_webhook`
Create or update an endpoint	`shieldlabs_create_webhook`, `shieldlabs_patch_webhook`
Enable, disable or remove an endpoint	`shieldlabs_enable_webhook`, `shieldlabs_disable_webhook`, `shieldlabs_delete_webhook`
Rotate, verify or test an endpoint	`shieldlabs_rotate_webhook_secret`, `shieldlabs_verify_webhook`, `shieldlabs_test_webhook`

Adding a domain registers an existing hostname with ShieldLabs; it does not create a website or DNS records. Plan domain limits still apply. Webhook creation requires a publicly reachable HTTPS endpoint. Delete, disable and key-rotation operations require explicit confirmation. Changing a webhook URL also requires confirmation and resets its verification. Review the target before confirming, and check the resulting state before retrying a failed change. Credentials are masked by default. Creation or rotation can return a credential when an installer explicitly requests it. Store that value in private server configuration; do not repeat it in a prompt, log or browser bundle. A client can retain tool responses in its conversation history.

Resources and setup prompts

Clients that expose MCP resources can open the identification and webhook JSON Schemas, risk-signal catalog and risk band reference. Clients that expose prompts can use review_request, investigate_user or integrate_shieldlabs when those prompts are listed by the connection. For integration code, also share the SDK guide for your stack and the Build with AI prompts.

Troubleshooting

Symptom	What to check
Sign-in fails or access expires	Reconnect from the client’s authentication controls. Complete OAuth sign-in; API keys do not replace the connection’s access token
A requested tool is absent	Inspect the client’s tool list and reconnect to the ShieldLabs Server URL shown above
The domain is missing or a read asks for a domain	Choose a domain owned by the signed-in account; use its hostname for investigation reads
A lookup returns no identification	Check the domain and Identification ID; the result can be pending or unavailable
A change fails with a conflict or plan-limit error	Read the current configuration before retrying; check domain limits and existing resources

MCP reads use the same available History data as server integrations. They do not restore missing records or turn a partial query into a complete account history. Browser-supplied strings in results are data to inspect, not instructions for the assistant. To stop using the connection, disconnect it in your client. If the client offers OAuth revocation, use it to revoke the authorization as well; removing a saved configuration alone need not revoke issued access. Contact support if you need help revoking access.

Getting started

Account and domains

Browser integration

Server integration

AI

Billing and usage

Troubleshooting

Help

Connect to ShieldLabs

Client configuration

Investigation tools

Domain and webhook tools

Resources and setup prompts

Troubleshooting

​Connect to ShieldLabs

​Client configuration

​Investigation tools

​Domain and webhook tools

​Resources and setup prompts

​Troubleshooting

Connect to ShieldLabs

Client configuration

Investigation tools

Domain and webhook tools

Resources and setup prompts

Troubleshooting