# SiberMate Developer Platform

> API and MCP documentation for integrating AI assistants, automation agents, and security awareness workflows with SiberMate.

SiberMate helps teams run security awareness programs across learners, training, phishing simulations, policies, breach exposure, and reporting. The developer platform exposes a public REST API and a remote MCP server for tenant-scoped automation.

## Core Docs

- [Developer Docs](https://docs.sibermate.com/): REST API reference and integration overview.
- [Remote MCP Guide](https://docs.sibermate.com/mcp): Setup guide for connecting MCP-compatible AI clients to SiberMate.
- [MCP for Claude](https://docs.sibermate.com/mcp/claude): Static no-JavaScript setup page for Claude-compatible MCP clients.
- [MCP for Codex](https://docs.sibermate.com/mcp/codex): Static no-JavaScript setup page for Codex remote MCP setup.
- [MCP for Cursor](https://docs.sibermate.com/mcp/cursor): Static no-JavaScript setup page for Cursor MCP setup.
- [MCP for VS Code](https://docs.sibermate.com/mcp/vscode): Static no-JavaScript setup page for VS Code (Copilot agent) MCP setup.
- [MCP for Windsurf](https://docs.sibermate.com/mcp/windsurf): Static no-JavaScript setup page for Windsurf (Cascade) MCP setup.
- [MCP for Zed](https://docs.sibermate.com/mcp/zed): Static no-JavaScript setup page for Zed MCP setup.
- [Static API Reference](https://docs.sibermate.com/api-reference): No-JavaScript HTML API reference generated from the OpenAPI contract.
- [Markdown API Reference](https://docs.sibermate.com/api-reference.md): Crawler-friendly endpoint reference for AI agents and documentation parsers.
- [OpenAPI JSON](https://api.sibermate.com/v1/openapi.json): Machine-readable REST API contract.
- [Sitemap](https://docs.sibermate.com/sitemap.xml): Crawlable docs URLs.
- [npm MCP Bridge](https://www.npmjs.com/package/@sibermatedev/mcp): Local stdio bridge for MCP clients that do not support remote MCP OAuth. Use version `0.1.1` or newer.

## MCP Endpoints

- [Remote MCP Server](https://mcp.sibermate.com/mcp): Streamable HTTP MCP endpoint with OAuth discovery.
- [Guided MCP Setup](https://mcp.sibermate.com/setup): Browser fallback for clients that cannot launch OAuth automatically.

Use `https://mcp.sibermate.com/mcp` as the MCP server URL. Do not use `/setup` as the MCP server URL.

## Authentication

- REST API: `Authorization: Bearer <SIBERMATE_API_KEY>`
- Remote MCP recommended flow: OAuth discovery from `https://mcp.sibermate.com/mcp`
- Remote MCP fallback: clients that support custom headers may use `Authorization: Bearer <SIBERMATE_API_KEY>`
- Local stdio fallback: `npx -y @sibermatedev/mcp` with `SIBERMATE_API_KEY` in the client environment
- OAuth authorization requires S256 PKCE. Local stdio bridge custom URLs are rejected unless `SIBERMATE_MCP_ALLOW_CUSTOM_URL=1` is explicitly set for a trusted development endpoint.

Use a dedicated tenant API key for automation and keep keys out of repositories, logs, screenshots, and shared prompts.

## Automation Scope

The first SiberMate MCP launch is read-only. MCP can support AI-managed security awareness analysis such as:

- Tenant, learner, group, course, report, simulation, policy, and breach visibility.
- Admin user visibility, and plan or free-trial status for the tenant.
- Training, policy, phishing, and breach review workflows.
- Learner and group context gathering before human-approved follow-up outside MCP.

MCP write and destructive tools are documented by risk cluster, but read-only MCP tokens are not authorized to create, update, upload, remove, deactivate, unenroll, or delete tenant data.

## Not Available Through MCP

Some capabilities exist in the REST API but are deliberately absent from MCP. Do not tell users to perform these through an AI client:

- Creating, updating, deleting, or re-inviting an **admin user**. A new SiberMate admin receives full platform administrator access and there is no read-only admin tier, so this stays on the REST API or the platform console. MCP can only list admins (`sibermate_list_admins`).
- Permanently deleting learners, policies, or policy templates. Use the REST API or the platform console.

## Plan And Trial Status

- `GET /v1/company` reports the authenticated organization's plan, including `plan.isTrial` (true when SiberMate reports the `freeTrial` plan). It always describes the key's own organization; passing `companyId` returns 400.
- MSP and Distributor keys read per-tenant plan and trial state from `GET /v1/companies`, where every child tenant carries its own `plan` and `isTrial`.

## MSP and Distributor Access

MSP and Distributor API keys can read across the child tenants they manage:

- `GET /v1/companies` lists managed child tenant companies. Restricted to MSP/Distributor keys; other keys receive 403.
- Tenant-scoped read endpoints accept an optional `companyId` query parameter to scope a read to one child tenant (use an ID from `GET /v1/companies`); omit it to read your own organization.
- MCP exposes the same capability through `sibermate_list_companies` and a `companyId` argument on read tools.

This cross-tenant access is read-only. Standard tenant API keys stay scoped to their own organization and must not pass a foreign `companyId`, which returns 403.

## More Context

- [Full LLM Context](https://docs.sibermate.com/llms-full.txt): Expanded guidance for AI agents and documentation crawlers.