---
title: MCP Server
description: Connect AI assistants and agent frameworks to 1Security over the Model Context Protocol - the same read-only data as the REST API, exposed as typed tools with the same keys, scopes, and limits.
icon: Bot
---

1Security ships a built-in **MCP server** (Model Context Protocol) so an AI
assistant - Claude, a SOC copilot, or any agent framework that speaks MCP - can
query your tenant's security data directly. It exposes the same read-only data
as the [REST API](/en/docs/reference/api), as typed tools: an assistant
connected to it can answer "which detections opened this week?", pull the audit
trail for a user, or fetch the compliance status document, without you writing
any connector code.

The MCP server and the REST API are one surface. Same API keys, same scopes,
same plan gate, same rate limit, same response shapes. A tool call and the
matching REST request return byte-identical payloads.

## Endpoint

The server speaks the MCP **Streamable HTTP** transport and is stateless - each
call is a self-contained request-response cycle, with no session to establish.

| Deployment        | MCP endpoint                               |
| ----------------- | ------------------------------------------ |
| Cloud (SaaS)      | `https://api.1security.ai/api/v1/mcp`      |
| BYOC / On-Premise | `https://<your-1security-host>/api/v1/mcp` |

Only `POST` is supported. There is no server-initiated notification stream
(`GET` returns `405`), which is exactly what stateless MCP clients expect.

## Authentication

Authenticate with the same [per-tenant API key](/en/docs/reference/api#authentication)
the REST API uses, sent as a bearer token:

```
Authorization: Bearer 1sec_live_…
```

Keys are created in the dashboard under **Settings → API**. The key's scopes
decide which tools the server registers: `tools/list` only ever shows what the
key can actually call, so a logs-only key presents a logs-only server.

## Connecting a client

For Claude Code:

```bash
claude mcp add 1security --transport http https://api.1security.ai/api/v1/mcp \
  --header "Authorization: Bearer $ONESEC_API_KEY"
```

For clients configured with JSON (Claude Desktop via `mcp-remote`, agent
frameworks, custom hosts):

```json
{
  "mcpServers": {
    "1security": {
      "type": "http",
      "url": "https://api.1security.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer 1sec_live_…"
      }
    }
  }
}
```

Then ask the assistant to call `ping` - it returns the tenant, key name, and
scopes the key maps to, which rules out the usual setup mistakes before you
rely on it.

<Callout type="warn">
  The MCP endpoint is for **server-side clients** (desktop assistants, agent
  runtimes, backend services). Browser-based MCP clients are blocked by the
  API's CORS policy.
</Callout>

## Tools

Each tool mirrors one REST endpoint - same parameters, same fields, same
pagination. The REST [endpoint reference](/en/docs/reference/api#endpoints)
documents every parameter and response field in detail.

| Tool                      | REST equivalent             | Scope                  |
| ------------------------- | --------------------------- | ---------------------- |
| `ping`                    | `GET /ping`                 | none                   |
| `list_logs`               | `GET /logs`                 | `logs:read`            |
| `list_detections`         | `GET /detections`           | `detections:read`      |
| `list_policy_scans`       | `GET /policy-scans`         | `policy-scans:read`    |
| `list_notifications`      | `GET /notifications`        | `notifications:read`   |
| `list_actions`            | `GET /actions`              | `actions:read`         |
| `list_security_alerts`    | `GET /security-alerts`      | `security-alerts:read` |
| `get_security_alert`      | `GET /security-alerts/{id}` | `security-alerts:read` |
| `get_agent_evidence_pack` | `GET /evidence/agents`      | `evidence:read`        |
| `get_compliance_status`   | `GET /compliance/status`    | `evidence:read`        |

All tools are annotated read-only (`readOnlyHint`), so MCP hosts that gate
write-capable tools behind approval can auto-approve them safely. Nothing the
MCP server exposes can change anything in 1Security or in your Microsoft 365
tenant.

### Pagination and filters

List tools return the same envelope as the REST API:

```json
{
  "data": [ … ],
  "pagination": { "nextCursor": "eyJvIjo1MH0", "hasMore": true, "limit": 50 }
}
```

To fetch the next page, the assistant passes `nextCursor` back as the `cursor`
argument. Filters that accept several values take a comma-separated string
(`"severity": "high,critical"`), timestamps are ISO-8601 UTC - identical to the
REST query parameters, so everything the [API reference](/en/docs/reference/api)
says about filtering applies verbatim.

## Limits

- **Read-only.** There are no write tools; remediation stays in the dashboard
  and in policies.
- **Same rate limit as REST.** Tool calls and REST requests draw from the same
  600 requests/minute budget per key.
- **Stateless.** No subscriptions or push notifications - an assistant that
  wants fresh data calls the tool again.
- **One tenant per key**, exactly as with the REST API.

## Next

<Cards>
  <Card
    title="API reference"
    href="/en/docs/reference/api"
    description="The full contract behind every tool: parameters, fields, error codes."
  />
  <Card
    title="SIEM integration guide"
    href="/en/docs/guides/siem-integration"
    description="Polling pattern, backfill, and wiring into Sentinel, Splunk, QRadar, or Elastic."
  />
</Cards>