Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.konstantly.com/llms.txt

Use this file to discover all available pages before exploring further.

The MCP server’s security posture mirrors the rest of Konstantly’s API: bearer-token auth, per-user permissions, audit log, rate limits. This page covers what’s specific to MCP and what to do operationally.

​
Rate limits

Two layers, both implemented as Redis sliding windows:

​
Per-key limits

Set by license tier:
TierPer minutePer day
Pro601,000
Enterprise600100,000
When a limit is exceeded, the API returns: 
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error":"Rate limit exceeded (minute). Retry after 12s.","code":"MCP_RATE_LIMITED"}
The MCP server automatically retries up to 3 times with backoff, honoring the Retry-After indication. A well-behaved agent won’t trip these in normal use.

​
Per-IP limits on failed auth

10 failed authentication attempts per minute per source IP. Designed to make brute-force enumeration noisy (you can detect it in logs) and to throttle bad actors without affecting legitimate use. 
HTTP/1.1 429 Too Many Requests
{"error":"Too many failed MCP authentication attempts. Retry after 47s.","code":"MCP_AUTH_RATE_LIMITED"}
If you’re seeing this in legitimate flows, your tool is misconfigured — most likely sending an expired or wrong key. Fix the env var.

​
Key hygiene

​
Treat keys like passwords

MCP keys are bearer tokens. Anyone holding the key can act as the issuing user within the bounds of that user’s permissions and license tier. Same exposure model as a GitHub PAT, AWS access key, or Stripe API key. Specifically:
  • Don’t commit keys to git
  • Don’t paste keys into Slack / Discord / email
  • Don’t share keys between team members (each person should issue their own)
  • Don’t reuse a key across multiple machines if you can avoid it (one per device makes revocation more surgical)

​
Storage on customer devices

The key lives in plaintext in your AI tool’s config file:
  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
  • Cursor: ~/.cursor/mcp.json
If your laptop is compromised, the key is too. Treat it accordingly. OS-keychain integration is on the roadmap for v1.1 — for now, the file-on-disk model is the same as how AWS CLI and many other developer tools handle credentials.

​
Revoke on device loss

If a device with a stored key is lost / stolen / sold / handed to another person:
  1. Go to Settings → MCP Keys in Konstantly
  2. Find the key for that device (use the name you gave it — “My laptop”, “Production agent”)
  3. Click the trash icon → confirm
The key stops working within seconds. No re-deploy needed; the next MCP call from that device 401s.

​
Rotation

v1 keys don’t expire automatically. Best practice:
  • Calendar reminder to rotate every 90 days
  • After each org change (someone leaves, role changes)
  • Whenever you suspect compromise
Optional expiry / auto-rotation is on the v1.1 roadmap. Until then, rotation is manual.

​
Audit log

Every MCP write-tool call writes two events to your tenant’s audit log:
  1. The action event — same as a UI-driven action (e.g., COURSE_ASSIGN, USER_BAN)
  2. MCP_TOOL_CALL event — explicitly tags the call as MCP-driven, with the tool name and redacted args in the data column
This gives you two views:
  • “What happened?” — filter audit log normally; results include both UI and MCP-driven actions, indistinguishable from each other (which is correct — they’re the same logical action).
  • “What did MCP do?” — filter on eventType=88 (MCP_TOOL_CALL) for a fleet-wide view of agent-driven activity per quarter, per user, per tool.
Read tools are not audited per-call — too high-volume. Instead they’re tracked in chat_usage (visible via /api/v2/chat/usage with intentType="mcp_tool").

​
Telemetry you get for free

Each MCP call generates:
  • chat_usage row — intentType="mcp_tool", context=toolName, mcpApiKeyId, durationMs, isSuccess. Visible in the existing AI Usage dashboard.
  • PostHog event mcp_tool_invoked — fleet-wide analytics for tool-selection rates, success/failure ratios, per-tier usage.
For ops teams: spike in success: false for a given tool is a strong signal of either a misconfigured key, a tool description the LLM is misunderstanding, or a backend regression.

​
Threat model

What the security posture defends against:

​
Defended

ThreatMitigation
Key brute-force256 bits of entropy = ~10⁷⁷ guesses required. Mathematically infeasible. Per-IP rate limit on auth failures adds telemetry signal.
Cross-tenant data accessPer-request tenant resolution by subdomain. Key from tenant A used on tenant B’s URL fails at lookup (B’s mcp_api_key table doesn’t have A’s hash).
Privilege escalationCapabilities endpoint filters tools by permission BEFORE registering with the LLM. Each endpoint independently re-checks server-side. Layered defense.
License downgrade bypassLicense tier read fresh per request. Pre-issued write keys silently clamped.
Permission revocation lagNo permission cache. Revoking a permission immediately blocks the next MCP call requiring it.
Timing attack on key validationConstant-time SHA-256 hash comparison (crypto.timingSafeEqual).
Information leak via error responsesAll auth failures return the same opaque 401. No distinction between “bad key” / “revoked key” / “license off”.
CSRFNot applicable — MCP server is server-to-server, browser never sees X-MCP-Key.
Session fixation via MCPMCP auth synthesizes a SessionData but never sets a cookie. No persistent session created.

​
Acknowledged risks (mitigation = ops + customer hygiene)

RiskWhy we accept itWhat you can do
Key stored plaintext on customer deviceIndustry-standard for developer tools today (AWS CLI, gh, npm). Keychain integration on roadmap.Treat the file like a password store. Encrypt the disk. Revoke on device loss.
Compromised npm publisher account → poisoned packageReal but not preventable from your side. We publish from a locked-down account and plan to ship sigstore provenance signatures so customers can verify via npm audit signatures.Pin a specific version in enterprise installs (@konstantly/mcp-server@0.1.0 instead of just the latest tag) to limit auto-flow of a compromised release.
Customer types wrong KONSTANTLY_URL and ships key to wrong hostThe MCP server now refuses non-HTTPS URLs (since v0.1.0), but it still trusts whatever host the customer typed.Use the install snippets from /settings/api-keys — copy-paste with the correct URL already filled in. Don’t hand-edit URLs.

​
Operational checklist before public-facing use

If you’re rolling MCP out to a team or customer base:
  • Audit your existing MCP keys — are any held by users who’ve left? Revoke them.
  • Document key-naming convention — “alex-laptop”, “prod-slack-bot” makes revoke decisions obvious. “key1” doesn’t.
  • Set a rotation calendar — 90 days is reasonable for human-held keys; CI bots can rotate weekly via automated re-issue.
  • Enable PostHog access for your security team — mcp_tool_invoked events show all agent activity in near-real-time.
  • Wire audit log to your SIEM — events 86 (MCP_KEY_CREATE), 87 (MCP_KEY_REVOKE), 88 (MCP_TOOL_CALL) are the MCP-relevant ones.
  • Train your admins to revoke keys before offboarding (same workflow as disabling SSO accounts).

​
AI Policy

How Konstantly handles AI processing — including which third-party providers receive customer data, how the MCP integration creates a sub-processing relationship with whichever AI agent you install (Claude, Cursor, etc.), and what we contractually disallow (e.g. training providers’ models on customer data) — is documented in our published AI Policy. Required reading for enterprise procurement reviews and EU AI Act compliance.

​
Next steps

Authentication

Key format, scopes, license-tier interactions

Permissions

Role-by-role tool matrix

Tools Reference

All 18 tools

Quickstart

Try it in 5 minutes