--- 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:///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. In the **demo tenant** the MCP snippets under **Settings → API → MCP** already embed the demo's shared read-only key - paste them into your client as-is to try the tools against the demo dataset. ## 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. 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. ## 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_tenants` | `GET /tenants` | none | | `list_logs` | `GET /logs` | `logs:read` | | `list_detections` | `GET /detections` | `detections:read` | | `get_detection` | `GET /detections/{id}` | `detections:read` | | `list_policy_scans` | `GET /policy-scans` | `policy-scans:read` | | `get_policy_scan` | `GET /policy-scans/{id}` | `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` | | `list_users` | `GET /users` | `users:read` | | `get_user` | `GET /users/{id}` | `users:read` | | `list_agents` | `GET /agents` | `agents:read` | | `get_agent` | `GET /agents/{id}` | `agents:read` | | `list_files` / `get_file` | `GET /files(/{id})` | `files:read` | | `list_groups` / `get_group` | `GET /groups(/{id})` | `groups:read` | | `list_sites` / `get_site` | `GET /sites(/{id})` | `sites:read` | | `list_apps` / `get_app` | `GET /apps(/{id})` | `apps:read` | | `list_devices` / `get_device` | `GET /devices(/{id})` | `devices:read` | | `list_emails` / `get_email` | `GET /emails(/{id})` | `emails:read` | | `list_licenses` / `get_license` | `GET /licenses(/{id})` | `licenses:read` | | `list_sensitive_info_types` / `get_sensitive_info_type` | `GET /sensitive-info-types(/{id})` | `sensitive-info:read` | | `get_agent_evidence_pack` | `GET /evidence/agents` | `evidence:read` | | `get_compliance_status` | `GET /compliance/status` | `evidence:read` | | `get_copilot_readiness` | `GET /copilot-readiness` | `evidence:read` | | `get_security_score` | `GET /security-score` | `evidence:read` | | `list_compliance_snapshots` | `GET /compliance/snapshots` | `evidence:read` | | `list_report_templates` | `GET /reports/templates` | `evidence:read` | | `get_report` | `GET /reports/templates/{id}/render` | `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. Every list tool also tells the assistant what it can pass: each argument description ends with the values the server accepts (or what a free value looks like) and an example, and the tool description ends with worked examples such as `{"severity":"high,critical","from":"<24 hours ago, ISO-8601>"}`. They are the same examples and allowed values the [API reference](/en/docs/reference/api) shows under each endpoint and the dashboard playground offers as presets - one catalog on the server feeds all three. ## 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 connection.** A regular key is bound to its tenant. An [organization-wide key](/en/docs/reference/api#organization-wide-keys-mssp) (MSSP) works here too: add an `X-Tenant-Id` header next to the `Authorization` header in the client configuration - one MCP server entry per tenant, each pointing at the same endpoint with a different tenant id (`list_tenants` shows the ids). ## Next