> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect through MCP

> Connect an AI client to ShieldLabs, authenticate it and use identification, domain and webhook tools.

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](https://docs.shieldlabs.ai/quickstart.md) installed on the site you protect.

## Connect to ShieldLabs

**1. Open MCP setup**

Sign in to the [analytics dashboard](https://app.shieldlabs.ai/) and open **Integration > MCP**. Choose your client and copy its connection settings. Use the Server URL displayed there.

The server endpoint is:

```text theme={null}
https://mcp.shieldlabs.ai/mcp
```

**2. 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.

**3. Sign in and authorize the connection**

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.

**4. 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**

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

```bash theme={null}
codex mcp add shieldlabs --url https://mcp.shieldlabs.ai/mcp
codex mcp login shieldlabs
```

**Claude Code**

```bash theme={null}
claude mcp add --transport http shieldlabs https://mcp.shieldlabs.ai/mcp
```

Open `/mcp`, choose ShieldLabs and complete authentication.

**Cursor**

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

```json theme={null}
{
  "mcpServers": {
    "shieldlabs": { "url": "https://mcp.shieldlabs.ai/mcp" }
  }
}
```

Complete the sign-in flow when prompted.

**VS Code**

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

```json theme={null}
{
  "servers": {
    "shieldlabs": {
      "type": "http",
      "url": "https://mcp.shieldlabs.ai/mcp"
    }
  }
}
```

Complete the sign-in flow when prompted.

**ChatGPT and Claude**

In a client that supports custom remote MCP connectors, add a connector named **ShieldLabs** with the Server URL and complete OAuth sign-in. Availability and the location of connector settings depend on your client and workspace settings. **Integration > MCP** in the ShieldLabs analytics dashboard provides the client-specific instructions.

## 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](https://docs.shieldlabs.ai/api/server-api.md#response-contracts).

Try prompts such as:

```text theme={null}
For example.com, review Identification ID <IDENTIFICATION_ID>.
Explain the returned score and detections. If no result is available, say so.
```

```text theme={null}
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](https://docs.shieldlabs.ai/api/sdks.md) and the [Build with AI prompts](https://docs.shieldlabs.ai/build-with-ai.md).

## 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](https://docs.shieldlabs.ai/support.md) if you need help revoking access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.