Connect Konstantly to Claude, Cursor, and other AI agents (MCP)

The Konstantly MCP server brings your training data into the AI tools you already use. Ask Claude Desktop *"who's overdue on the OSHA refresher?"* and it answers from your real data. Tell Cursor *"assign the safety training to the warehouse team, deadline Friday"* and it happens — with the same permissions you'd have in the browser.

> MCP (Model Context Protocol) is an open standard from Anthropic that lets AI agents talk to outside systems through a shared interface. Think of it as a universal port: any AI tool that speaks MCP can connect to any service that exposes an MCP server. Today that includes Claude Desktop, Claude Code, Cursor, and any custom internal agent you build.

What you can do

Once connected, your AI agent has 25 tools to read and act on Konstantly data:

Read (Business and Enterprise):

• Search users and courses by name
• Pull compliance reports for any course or group ("who's done OSHA training?")
• Check certificate expiry dates ("what's expiring in the next 60 days?")
• View team statistics and leaderboards
• Inspect the audit log

Write (Business and Enterprise):

• Assign single courses or whole learning paths to learners or groups
• Ban/unban users and update emails (e.g. for offboarding)
• Clone courses to fork a copy for a new audience

AI course generation (Business and Enterprise) — your agent gets seven more tools that *create and refine* courses: generate a complete course from a prompt or a PDF, then iterate on it without ever opening the platform editor. Covered in the "AI course generation" section below.

Before you start

You'll need:

• A Konstantly workspace on Business or Enterprise plan (the MCP integration is gated by license tier; the Free plan doesn't see it)
• Admin or super-user access to that workspace (the mcp_manage permission, which Konstantly grants to the Administrator role by default)
• One of the supported AI tools installed: Claude Desktop, Claude Code, or Cursor
• Node.js 18 or higher on the machine where the AI tool runs (used to run the MCP server via npx)
• About 5 minutes

Step 1: Generate your MCP key

In your Konstantly workspace:

1. Go to Settings → MCP Keys
2. Click Generate key
3. Give it a recognizable name — e.g. *"My MacBook"*, *"Production agent"*, *"Slack bot"*
4. Choose scopes:

- Read — for analysis, reporting, lookups

- Write — for assignments, user management, course operations

1. Click Generate

The full key appears once. It looks like:

kmcp_a8f3b2k9X7yZqWpL3mN8RvU2sT5dH6jK4F1gA9oP

Copy it immediately. Closing the dialog without copying means you'll have to revoke and regenerate.

> Treat MCP keys like passwords. The key acts as you — anyone holding it inherits your permissions in Konstantly. Don't paste keys into Slack, don't commit them to git, don't share them with teammates (each person should generate their own).

Step 2: Install in your AI tool

Pick the tool you use most. The MCP server itself is published to npm as @konstantly/mcp-server — you don't need to install anything manually; the config below tells your AI tool to fetch it on demand via npx.

Claude Desktop (most common)

Open the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it. Add (or merge into) the following:

{
  "mcpServers": {
    "konstantly": {
      "command": "npx",
      "args": ["-y", "@konstantly/mcp-server"],
      "env": {
        "KONSTANTLY_MCP_KEY": "kmcp_a8f3b2k9X7yZ...",
        "KONSTANTLY_URL": "https://your-instance.konstantly.com"
      }
    }
  }
}

Replace:

• KONSTANTLY_MCP_KEY with the key you copied in step 1
• KONSTANTLY_URL with your Konstantly workspace URL (the same one you type into your browser)

Quit and reopen Claude Desktop. The 🔌 menu in the conversation window now shows konstantly with its tool list.

Claude Code

One-line install:

claude mcp add konstantly \
  --env KONSTANTLY_MCP_KEY=kmcp_a8f3b2k9X7yZ... \
  --env KONSTANTLY_URL=https://your-instance.konstantly.com \
  -- npx -y @konstantly/mcp-server

Claude Code picks it up automatically.

Cursor

Open (or create) ~/.cursor/mcp.json:

{
  "mcpServers": {
    "konstantly": {
      "command": "npx",
      "args": ["-y", "@konstantly/mcp-server"],
      "env": {
        "KONSTANTLY_MCP_KEY": "kmcp_a8f3b2k9X7yZ...",
        "KONSTANTLY_URL": "https://your-instance.konstantly.com"
      }
    }
  }
}

Restart Cursor. The Konstantly tools appear in the agent panel.

Step 3: Try it

Open your AI tool and ask something. Start with a read-only query:

> *"Find a user named Sarah Chen and tell me her training status."*

The agent uses two tools in sequence (find_user then list_assignments) and answers in plain English.

A few more to try:

> *"How many people in the warehouse group have completed the safety refresher this year? I need this for the audit."*

> *"Show me everyone whose certificates are expiring in the next 60 days, sorted by date."*

> *"What's my own training status?"*

If you have write access:

> *"Assign the new-hire bundle to user 42, deadline two weeks from now."*

> *"Roll out the Q4 compliance refresher to the entire Sales team — due in 30 days."*

Each action writes an entry to your audit log (Settings → Action Log), tagged as MCP-driven so you can separate agent actions from human admin actions later.

Verifying it works

If something looks off — the agent says it can't find tools, or queries fail — turn on debug mode by adding to your env block:

"env": {
  "KONSTANTLY_MCP_KEY": "kmcp_...",
  "KONSTANTLY_URL": "https://your-instance.konstantly.com",
  "KONSTANTLY_MCP_DEBUG": "1"
}

Restart your AI tool. The MCP server logs every request and response to its error output — you'll see auth attempts, retries, and tool calls. Most issues fall out immediately:

Managing keys

The Settings → MCP Keys page shows all keys you've issued, with:

• The friendly name you gave each one
• The first few characters of the key (so you can identify it without seeing the full secret)
• When it was created and last used
• A revoke button

Revoke a key

Click the trash icon next to any key and confirm. The key stops working within seconds — the next call from any agent using it returns 401.

You don't need to update the AI tool's config beforehand. The key just becomes invalid; the agent will surface the error on the next prompt.

Rotate keys regularly

We recommend rotating keys every 90 days, and immediately when:

• A teammate who held a key leaves the company
• A device with a stored key is lost, stolen, or sold
• You suspect a leak (e.g. accidentally committed to git)

Rotation = generate a new key → update your tool's config → revoke the old key. Total time: under a minute.

Per-device keys

Best practice is one key per device per agent. If you have Claude Desktop on your laptop AND Cursor on your desktop AND a Slack bot, that's three keys. Revoking one (e.g. if you lose the laptop) doesn't break the others.

Security at a glance

A few facts about how MCP integrates with Konstantly's existing security model:

• Same permissions as the UI. Each key inherits the permissions of the user who created it. A learner-issued key cannot access admin data. A manager-issued key can only ban users below them in the role hierarchy.
• Every write tool call is audited. Compliance reports can filter "actions taken by an agent" by querying audit event type 88 (MCP_TOOL_CALL).
• License downgrades are silent and immediate. Drop from a paid plan to Free and every existing key stops working — no re-issue required.
• Rate-limited per key. Business: 60 calls per minute, 1,000 per day. Enterprise: 600 per minute, 100,000 per day. The MCP server retries on 429 with backoff, so legitimate usage rarely sees these.
• 256 bits of entropy per key. Brute-forcing is mathematically infeasible. Failed-auth attempts are throttled per source IP to catch enumeration attempts in telemetry.

For the full security model, see the MCP Security documentation. For how Konstantly handles AI processing across all features (Ask Konstantly, course generation, and the MCP integration with third-party agents like Claude and Cursor), see our AI Policy.

Pricing

Upgrade from Settings → Billing, or talk to sales.

AI course generation (Business and Enterprise)

Seven additional MCP tools let the agent build, then iterate on, complete courses without the customer ever opening Konstantly.

Build a course

Iterate on a course

How it looks in Claude

You: Build a confined-spaces safety course for warehouse staff from
     this OSHA PDF I just shared. 8 modules + a final quiz.

Claude:  upload_source_material  ~/Downloads/osha-confined-spaces.pdf
         ↳ Indexed · 47 chunks

         create_course_from_files  sessionId=4f1c…, chapters=8
         ↳ Queued · jobId=ai-course-2381

         get_course_generation_status  jobId=ai-course-2381
         ↳ status=completed · courseId=2419

         "Confined-Spaces Safety for Warehouse Staff" is live in
         your workspace — 8 modules + a 10-question final quiz,
         grounded in the OSHA PDF. Open course #2419 to review.

You: Looks good but it's missing emergency rescue procedures. Add a
     section on rescue at the end before the final quiz.

Claude:  refine_course  courseId=2419,
                        feedback="Add a 2-lesson section on confined-
                        space rescue procedures with a checkpoint
                        question, placed just before the final quiz."
         ↳ Added 3 new elements (2 lessons + 1 question) + 4
           transitions to course #2419.

         The rescue section is live — open the course to review the
         new content.

You: Question 5821 is too easy. Make it harder.

Claude:  regenerate_question  questionId=5821, feedback="Make harder"
         ↳ Rewrote the question with tougher distractors. Previous
           version is in your audit log.

A few practical notes

• Rate limit: 5 AI calls per key per day, 50 per tenant per day. Generation and refinement tools share this bucket — each AI call counts as one regardless of which tool fired it. Plenty for human use.
• Source materials: PDF, DOC/DOCX, PNG, JPG, GIF, WebP. 20 MB max per file. Multiple files in one session ("here's the safety doc AND the procedure manual") work — call upload_source_material once per file with the same sessionId, then create_course_from_files once.
• Refinement is safe: refine_course never deletes or modifies existing content (append-only). regenerate_question only replaces the targeted question's text and options. regenerate_lesson only updates the lesson's AI brief — pages you've already created in the editor stay untouched.
• Permission gates per call: write-scope alone isn't enough for refinement / regeneration — the calling user must actually have edit rights on the specific course. Your role's course_edit permission gets you in the door; ownership / sharing decides whether you can mutate this particular course.
• Async via background job for generation; sync for refinement: initial generation takes 10–30 seconds and runs in the background. Refinement and per-element regeneration are faster (~5–10 seconds) and run synchronously.
• You stay in control: every course is created in draft. Open it in Konstantly to review and publish.
• Audit log: each AI action writes a dedicated event on the course — AI_COURSE_GENERATE, AI_COURSE_REFINE, AI_QUESTION_REGENERATE, or AI_LESSON_REGENERATE — with the issuing key recorded for compliance review.

Common patterns

Daily compliance check

Ask your AI tool every Monday morning:

> *"Pull this week's compliance status for the warehouse OSHA training, and tell me who's overdue."*

Five seconds, no dashboard hunting. Pair with a weekly calendar reminder and you have an effortless compliance check-in.

Onboarding automation (HRIS-integrated setups)

If your team uses Claude or Cursor as part of a broader workflow with HRIS-aware tools (Workday, BambooHR, etc.), you can chain them:

> *"For every new hire created in Workday this week, assign the new-hire onboarding chain in Konstantly with a 30-day deadline."*

The agent calls Workday's MCP (or API) for the user list, then calls Konstantly's assign_chain for each new hire.

Recurring certification reminders

> *"Show me everyone whose forklift certification expires in the next 60 days. Then assign them the recertification course with a deadline two weeks before expiry."*

Two tools in sequence — list_certificates then assign_training per learner.

Audit prep (the killer scenario)

> *"I have an OSHA inspection Tuesday. Generate a compliance summary for confined-spaces and working-at-heights training across all warehouse staff over the last 12 months. Format it as a single document I can hand to the inspector."*

get_compliance_status + the agent's built-in document-formatting → finished report in under a minute.

Troubleshooting

The MCP Keys tab isn't visible

Either:

• Your plan doesn't include MCP (Business or Enterprise required), OR
• Your role doesn't have the mcp_manage permission. Talk to a workspace owner / administrator.

Claude Desktop doesn't show the konstantly tools after install

• Did you fully quit and reopen Claude Desktop? (On macOS, ⌘Q — not just closing the window.)
• Is the config file valid JSON? Open it in a JSON validator. A trailing comma or missing brace breaks the entire config.
• Run KONSTANTLY_MCP_DEBUG=1 and check Claude Desktop's MCP logs (Help → Show Logs).

"Permission denied" on a write tool I should have access to

• Your Konstantly role must include the underlying permission (e.g. user_assign for assign_training). Check Settings → Roles.
• Your MCP key must have write scope. Check Settings → MCP Keys — regenerate the key with write scope if it was issued read-only.
• Your license tier must be Business or Enterprise (mcpAccess: "full"). Check Settings → Billing.

Rate limited

If you're hitting 429s in normal use:

• Business plans have 60 calls/min — a chatty agent can hit this. Either upgrade to Enterprise (600/min) or batch your queries.
• Enterprise hitting 600/min usually means a runaway agent. Check KONSTANTLY_MCP_DEBUG=1 logs for an infinite loop.

"Too many failed MCP authentication attempts"

Your tool is sending an invalid key (revoked, typo, or wrong URL). Fix the env var. The block lifts after 60 seconds.

What MCP doesn't do yet

A few capabilities aren't shipped. We'll update this guide as they land:

• Extending deadlines, sending reminders — the agent can read assignment status today but can't push deadlines back or trigger reminder emails.
• Hosted MCP transport — currently the MCP server runs on the same machine as your AI tool (stdio transport). HTTP transport for hosted scenarios like Slack bots and internal dashboards is on the roadmap.
• Survey response analytics — the agent can generate surveys today via create_course_from_prompt but can't query individual response data yet.

See also

• MCP technical reference — full tool list, authentication details, security model
• Connect to Zapier — for no-code automation across 8,500+ other apps
• Konstantly API — the underlying REST API that MCP wraps

If you run into anything not covered here, get in touch — we'll add it.