MCP Documentation

32 tools to build, test, and deploy AI agents from your terminal

Overview

Kopern exposes its entire platform through the Model Context Protocol (MCP) — an open standard for connecting AI tools and agents. With 32 tools covering the full agent lifecycle, you can build, test, grade, optimize, and deploy agents entirely from your terminal or IDE.

Key facts:

  • 32 MCP tools across 9 categories
  • 2 key types: agent-bound (32 tools) and user-level (30 tools)
  • 3 guided workflows via MCP Prompts
  • Tool annotations for smart client UIs
  • Zero dependencies — just Node.js 18+

Quick Start

Claude Code — one command:

claude mcp add kopern -- npx -y @kopern/mcp-server

Cursor / Windsurf — add to your .mcp.json:

{ "mcpServers": { "kopern": { "command": "npx", "args": ["-y", "@kopern/mcp-server"], "env": { "KOPERN_API_KEY": "kpn_your_key_here" } } } }

Get your API key

  1. Log in to kopern.ai
  2. Agent-bound key: open your agent → API Keys tab → Generate Key
  3. User-level key: go to Settings → Personal API Key → Generate
  4. Copy the key immediately — it is shown only once

Then set it as an environment variable:

export KOPERN_API_KEY=kpn_your_key_here

The @kopern/mcp-server package is a lightweight stdio-to-HTTP bridge (5KB, zero deps).

Option 2: Direct HTTP

Add to your .mcp.json:

{ "mcpServers": { "kopern": { "type": "http", "url": "https://kopern.ai/api/mcp/server", "headers": { "Authorization": "Bearer kpn_your_key" } } } }

Authentication

Two Key Types

Key TypeScopeToolsHow to Create
Agent-boundTied to one agentAll 32 tools (includes kopern_chat, kopern_agent_info)Agent detail page → API Keys tab
User-levelNot bound to any agent30 platform toolsSettings → Personal API Key

When to use which:

  • Agent-bound: Chat with a specific agent via MCP, or when all operations target one agent
  • User-level: Platform operations — creating agents, managing teams, running grading across agents

Key Format

All keys use the kpn_ prefix followed by 32 random hex bytes (64 characters). Only the SHA-256 hash is stored — the plaintext key is shown once at creation and cannot be retrieved.

Rate Limits

  • 30 requests/minute per key (sliding window)
  • HTTP 429 response with Retry-After header when exceeded
  • Rate limits apply per-key, not per-user

Protocol Reference

Endpoint

POST https://kopern.ai/api/mcp/server Content-Type: application/json Authorization: Bearer kpn_your_key

Transport

Implements the MCP Streamable HTTP transport (spec 2024-11-05). All requests use JSON-RPC 2.0.

Supported Methods

MethodDescription
initializeHandshake — returns protocol version, capabilities, server info
tools/listList available tools (up to 32)
tools/callExecute a tool
prompts/listList guided workflows (3 prompts)
prompts/getGet a specific prompt template
pingKeepalive check

Initialize

{ "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "2024-11-05", "clientInfo": { "name": "my-client", "version": "1.0" } }, "id": 1 }

Response:

{ "jsonrpc": "2.0", "result": { "protocolVersion": "2024-11-05", "capabilities": { "tools": {}, "prompts": {} }, "serverInfo": { "name": "kopern-mcp", "version": "2.0.0" } }, "id": 1 }

Tools List

{ "jsonrpc": "2.0", "method": "tools/list", "id": 2 }

Returns all tools available for your key type, each with:

  • name: Tool identifier (e.g., kopern_create_agent)
  • description: What the tool does
  • inputSchema: JSON Schema for arguments
  • annotations: Hints for client UIs (readOnly, destructive, etc.)

Tools Call

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "kopern_create_agent", "arguments": { "name": "Support Bot", "system_prompt": "You are a helpful support agent.", "provider": "anthropic", "model": "claude-sonnet-4-6" } }, "id": 3 }

Response:

{ "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "Agent created successfully.\nAgent ID: abc123..." } ] }, "id": 3 }

Tool Reference

Agent Management (8 tools)

ToolDescriptionKey Type
kopern_chatSend a message to an agent (with tool calling)Agent-bound only
kopern_agent_infoGet agent metadataAgent-bound only
kopern_create_agentCreate a new agentAny
kopern_get_agentGet agent configurationAny
kopern_update_agentUpdate agent config, skills, tools, extensionsAny
kopern_delete_agentDelete an agentAny
kopern_list_agentsList all agentsAny
kopern_list_templatesList available templates (general + vertical)Any

kopern_create_agent

{ "name": "Support Bot", "system_prompt": "You are a helpful support agent for TechStore.", "description": "Customer support", "domain": "support", "provider": "anthropic", "model": "claude-sonnet-4-6", "builtin_tools": ["web_fetch", "memory"], "skills": [ { "name": "product-knowledge", "content": "# Products\n- Widget Pro: $99/mo..." } ] }

kopern_update_agent

Update any part of an agent: config fields, skills, tools, or extensions.

Config fields (replace on write):

{ "agent_id": "abc123", "system_prompt": "Updated prompt...", "builtin_tools": ["web_fetch", "memory", "code_interpreter"] }

Skills, tools, extensions (granular add/remove):

{ "agent_id": "Scout", "skills_add": [ { "name": "OSINT Sources", "content": "## How to find leads\n..." } ], "skills_remove": ["Old Skill Name"], "tools_add": [ { "name": "score_calculator", "description": "Calculate lead score", "parameters_schema": "{\"type\":\"object\",\"properties\":{\"revenue\":{\"type\":\"number\"}}}", "execute_code": "return { score: args.revenue > 1000000 ? 'high' : 'low' };" } ], "tools_remove": ["old_tool"], "extensions_add": [ { "name": "output_logger", "code": "return { action: 'continue' };", "events": ["after_response"], "blocking": false } ], "extensions_remove": ["old_hook"] }

All fields are optional. Only provided fields are updated. _add appends, _remove deletes by name.

kopern_deploy_template

{ "slug": "legal-assistant", "answers": { "specialite": "Droit des affaires", "cabinet": "Cabinet Dupont" } }

Grading & Optimization (6 tools)

ToolDescription
kopern_grade_promptQuick-grade a system prompt with test cases (no agent required)
kopern_create_grading_suiteCreate a persistent grading suite for an agent
kopern_run_gradingExecute a grading suite
kopern_get_grading_resultsGet detailed results for a grading run
kopern_list_grading_runsList past grading runs for a suite
kopern_run_autoresearchRun AutoTune optimization (iterative prompt improvement)

kopern_grade_prompt

{ "system_prompt": "You are a legal assistant...", "test_cases": [ { "name": "Contract review", "input": "Review this NDA clause: ...", "expected": "Identifies key risks and suggests improvements" }, { "name": "Greeting", "input": "Hello", "expected": "Professional greeting mentioning legal expertise" } ], "provider": "anthropic", "model": "claude-sonnet-4-6" }

kopern_run_autoresearch

{ "agent_id": "abc123", "suite_id": "suite456", "max_iterations": 5, "target_score": 0.95, "max_token_budget": 500000 }

Teams & Pipelines (4 tools)

ToolDescription
kopern_create_teamCreate a multi-agent team with execution mode
kopern_run_teamExecute a team with a prompt
kopern_create_pipelineCreate a multi-step pipeline for an agent
kopern_run_pipelineExecute a pipeline

kopern_create_team

{ "name": "Marketing Team", "description": "Content creation pipeline", "execution_mode": "sequential", "agents": [ { "agent_id": "strategist123", "role": "Content strategist", "order": 0 }, { "agent_id": "copywriter456", "role": "Copywriter", "order": 1 }, { "agent_id": "publisher789", "role": "Publisher", "order": 2 } ] }

Execution modes:

  • sequential: Agents run in order, each receiving the previous agent's output
  • parallel: All agents run simultaneously on the same prompt
  • conditional: First agent routes to the most appropriate specialist

kopern_run_team

{ "team_id": "team789", "prompt": "Create the editorial plan for this week" }

Connectors (7 tools)

ToolDescription
kopern_connect_widgetDeploy agent as an embeddable chat widget
kopern_connect_telegramConnect agent to a Telegram bot
kopern_connect_whatsappConnect agent to WhatsApp Business
kopern_connect_slackConnect agent to a Slack workspace
kopern_connect_webhookSet up inbound/outbound webhooks
kopern_connect_emailConnect Google/Microsoft email (OAuth)
kopern_connect_calendarConnect Google/Microsoft calendar (OAuth)

kopern_connect_widget

{ "agent_id": "abc123", "welcome_message": "Hi! How can I help?", "position": "bottom-right", "allowed_origins": ["https://mysite.com"] }

kopern_connect_webhook

{ "agent_id": "abc123", "type": "outbound", "name": "n8n Integration", "target_url": "https://my-n8n.cloud/webhook/kopern", "secret": "my_hmac_secret", "events": ["message_sent", "tool_call_completed"] }

Sessions & Monitoring (5 tools)

ToolDescription
kopern_list_sessionsList conversation sessions for an agent
kopern_get_sessionGet detailed session with messages and events
kopern_manage_memoryCRUD operations on agent memory (remember/recall/forget/list)
kopern_compliance_reportGenerate EU AI Act compliance report
kopern_get_usageGet token usage and cost metrics

kopern_manage_memory

{ "agent_id": "abc123", "action": "remember", "key": "company_name", "value": "TechStore Inc.", "category": "context" }

Actions: remember (create/update), recall (read by key or query), forget (delete by key), list (list all).

kopern_get_usage

{ "year_month": "2026-04", "include_history": true }

Portability (2 tools)

ToolDescription
kopern_export_agentExport agent as portable JSON (config, skills, tools, extensions)
kopern_import_agentImport agent from exported JSON

Tool Annotations

Every tool includes MCP annotations that help client UIs make smart decisions:

AnnotationMeaningExample Tools
readOnlyHint: trueSafe to auto-approve, no side effectslist_agents, get_session, get_usage
destructiveHint: trueMay permanently delete datadelete_agent
idempotentHint: trueSafe to retry without side effectsupdate_agent, connect_widget
openWorldHint: trueMakes external API callschat, grade_prompt, run_grading

Guided Workflows (MCP Prompts)

Three step-by-step workflows are available via prompts/list:

create-agent

Walks you through building an agent from scratch:

  1. Define the use case and domain
  2. Write the system prompt
  3. Add skills and tools
  4. Configure model and settings
  5. Create the agent

grade-and-improve

Iterative quality improvement cycle:

  1. Create or select a grading suite
  2. Run grading
  3. Analyze results and identify weaknesses
  4. Apply improvements
  5. Re-grade to measure progress

deploy-everywhere

Deploy an agent across all available channels:

  1. Set up embeddable chat widget
  2. Connect Telegram bot
  3. Configure Slack integration
  4. Set up webhooks for n8n/Zapier/Make
  5. Verify all deployments

Usage & Billing

Token Tracking

All tokens consumed through MCP are tracked and billed:

  • Firestore: Atomic increments in users/{userId}/usage/{yearMonth}
  • Stripe: Metered billing events for usage-based plans
  • Per-agent: Breakdown by agent for cost attribution

Plan Limits

Plan-specific operations are enforced:

  • kopern_run_grading, kopern_run_autoresearch — require grading quota
  • kopern_create_team, kopern_run_team — require teams quota
  • kopern_chat — counts against token limits

Cost Estimation

Token costs depend on the model used by each agent. See the Pricing page for details.

Self-Hosted

Run the MCP server locally with Docker:

# Clone and configure cp .env.example .env.local # Set Firebase, Stripe, and LLM keys # Start docker compose up -d

The self-hosted server exposes the same MCP endpoint at http://localhost:3000/api/mcp/server.

For fully local operation: Firebase Emulator + Ollama = zero cloud dependencies.

Registries

The Kopern MCP server is listed on:

RegistryStatusLink
npmPublished (v2.0.4)@kopern/mcp-server
SmitheryScore 80/100kopern.run.tools
GlamaApprovedglama.ai/mcp/servers
OpenToolsSubmittedopentools.com
MCPTotalSubmittedmcptotal.com

Troubleshooting

Connection Issues

"Invalid API key" — Verify your key starts with kpn_ and hasn't expired. Generate a new key in Settings.

"Rate limited (429)" — Wait for the Retry-After duration. Consider spreading operations across time.

"Tool not found" — Check your key type. kopern_chat requires an agent-bound key, not a user-level key.

Common Patterns

Agent-bound key but want platform tools? Agent-bound keys have access to all 32 tools including platform operations. Use one key for everything.

Multiple agents from one key? Use a user-level key and pass agent_id to tools that require it.

Webhook integration? Use kopern_connect_webhook to set up n8n/Zapier/Make integrations. Supports HMAC-SHA256 signature verification.

Changelog

DateChange
2026-04-05Agentic Engine Upgrade — parallel tool execution, billing audit
2026-04-04Image generation builtin, team image URL chaining, maxDuration 600s
2026-04-03Tool annotations, MCP Prompts (3 workflows), Smithery 80/100
2026-04-02MCP v2.0.0 — 32 tools, user-level keys, self-hosted Docker
2026-04-01MCP v1.1.0 — 19 tools (agent CRUD, grading, teams, connectors)
2026-03-01Initial MCP Streamable HTTP server