# MCP Server Seclai exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI-powered coding tools manage your agents and their definitions directly from your editor or terminal. ## Overview The MCP server provides tools for the full agent lifecycle: - **List, create, update, and delete** agents - **Read and update agent definitions** (steps, tags, configuration) - **Manage agent evaluations** — criteria CRUD, draft testing, and results inspection - **Manage knowledge bases** — create, update, and delete KB configurations - **Create, list, and configure content sources** — create, view, update, and delete sources - **Search resources** — find agents, knowledge bases, sources, solutions, memory banks, alerts, API keys, and governance policies - **Search documentation** — look up the Seclai docs by content (keyword or semantic) and get deep links to the right page and section - **Monitor alerts** — list, view, resolve, and comment on alerts; manage alert configurations - **Manage solutions** — create, update, delete solutions and link/unlink agents, KBs, and sources - **Agent AI assistant** — generate step configs and full agent workflows - **Solution AI assistants** — generate and execute plans for managing sources, knowledge bases, and full solution configurations - **Manage governance** — configure policies, settings, evaluations, and use the governance AI assistant - **Browse reference resources** like the agent definition schema and string substitutions This means you can ask your AI assistant things like _"create a new agent that summarizes RSS feeds daily"_, _"create a knowledge base from my podcast sources"_, _"change the polling interval on my news feed to hourly"_, _"show me any open alerts"_, _"use the AI assistant to generate a transform step that extracts article titles"_, _"create a solution to organize my podcast workflow"_, _"use the AI assistant to set up sources and a knowledge base for my new project"_, _"show me my governance stats"_, or _"use the governance assistant to add a PII policy"_ and it will use the MCP tools to make those changes in Seclai directly. ## Prerequisites Before setting up the MCP server, you need: 1. **A Seclai account** with an active subscription that includes API access 2. **An MCP-compatible client** such as Claude Desktop, Claude Code, Cursor, or Windsurf ### Authentication The MCP server supports two authentication methods: **OAuth (recommended)** — Most MCP clients support OAuth automatically. Simply enter the server URL and your client will open a sign-in page. No API key needed. OAuth provides automatic token refresh and doesn't require sharing secrets. **API key (fallback)** — For clients or environments that don't support OAuth, use a user-scoped API key via the `X-API-Key` header. Create one from the [API Keys](https://seclai.com/docs/api-keys) page. > Your plan must have **API access** enabled. Upgrade your plan in account settings if needed. > > If using API keys, MCP requires **user-scoped keys**. If you get an error about user association, re-create your API key. --- ## Available Tools The MCP server provides these tools: ### Agent Tools | Tool | Description | | ------------------------------------ | ------------------------------------------------------------------------ | | list_agents | List all agents in your account with pagination | | get_agent | Get an agent's metadata (name, description, trigger type) | | get_agent_definition | Get the full agent definition including steps and change_id | | create_agent | Create a new agent with an optional template | | update_agent | Update an agent's name and/or description | | update_agent_definition | Update an agent's definition with optimistic locking | | delete_agent | Delete an agent (cannot be undone) | ### Agent Evaluation Tools Use these tools to configure step-level quality criteria, run ad-hoc evaluation tests, and inspect evaluation outcomes. | Tool | Description | | --------------------------------------- | ------------------------------------------------------------------------------------------------ | | list_evaluation_criteria | List all evaluation criteria configured for an agent | | get_evaluation_criteria | Get one criteria including mode, tier, threshold, and result summary | | create_evaluation_criteria | Create criteria for a terminal step (step_id, evaluation_prompt, etc.) | | update_evaluation_criteria | Update criteria fields such as pass_threshold and evaluation_tier | | delete_evaluation_criteria | Delete a criteria by ID | | list_evaluation_results | List persisted evaluation results with filters and pagination | | run_evaluation | Run a persisted criteria against a specific agent_step_run_id | | test_draft_evaluation | Test draft evaluation settings before saving the criteria | `pass_threshold` is supported by create/update/test-draft tools and must be in the range `0.0` to `1.0`. ### Knowledge Base Tools | Tool | Description | | ---------------------------------- | ----------------------------------------------------------- | | list_knowledge_bases | List knowledge bases in your account with pagination | | get_knowledge_base | Get a knowledge base's details including its linked sources | | create_knowledge_base | Create a new knowledge base with at least one source | | update_knowledge_base | Update a knowledge base's name, description, or sources | | delete_knowledge_base | Delete a knowledge base (fails if referenced by agents) | ### Memory Bank Tools Memory banks give agents persistent conversation memory. See [Memory Banks](https://seclai.com/docs/memory-banks) for full details. | Tool | Description | | ----------------------------------------- | ----------------------------------------------------------------------- | | list_memory_bank_templates | List pre-built template configurations for common memory bank use cases | | list_memory_banks | List memory banks with pagination and sorting (by name or created_at) | | get_memory_bank | Get full details of a memory bank including embedding config | | create_memory_bank | Create a new memory bank with mode, compaction, and retention settings | | update_memory_bank | Update a memory bank's name, compaction prompt, or thresholds | | delete_memory_bank | Soft-delete a memory bank and its linked content source | | delete_memory_bank_source | Delete a bank's content source to reset stored data | | get_agents_using_memory_bank | List agents whose workflow references this memory bank | | get_memory_bank_stats | Get aggregated entry statistics with token/age distributions | | test_compaction_prompt | Test a compaction prompt with LLM-as-judge quality evaluation | ### Content Source Tools | Tool | Description | | --------------------------------------------- | -------------------------------------------------------------------- | | list_sources | List all content sources in your account with pagination | | get_source | Get detailed information about a content source | | create_source | Create a new content source (RSS feed, website, or content store) | | update_source | Update a source's name, polling interval, or retention settings | | delete_source | Delete a content source (soft delete) | | get_source_embedding_migration | Get the latest embedding migration status for a content store source | | start_source_embedding_migration | Start an embedding model migration for a content store source | ### Search Tools | Tool | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | search | Search resources in your account by keyword or UUID, with optional type filter | | search_docs | Search the Seclai documentation by content (`keyword` or `semantic`); returns `doc_slug` + section `anchor`, plus a `highlight` sentence in semantic mode | ### Alert Tools | Tool | Description | | -------------------------------- | --------------------------------------------------------------- | | list_alerts | List alerts for an agent or across your account, with filtering | | get_alert | Get full details of a specific alert instance | | change_alert_status | Resolve or re-open an alert | | add_alert_comment | Add a comment to an alert | | list_alert_configs | List alert configurations for an agent | | get_alert_config | Get details of a specific alert configuration | | create_alert_config | Create a new alert configuration for an agent | | update_alert_config | Update an existing alert configuration | | delete_alert_config | Delete an alert configuration | ### Solution Tools Solutions let you group related agents, knowledge bases, and content sources into projects. | Tool | Description | | -------------------------------------- | -------------------------------------------------------------------------- | | list_solutions | List all solutions in your account with pagination | | get_solution | Get solution details including linked agents, knowledge bases, and sources | | create_solution | Create a new solution to group related resources | | update_solution | Update a solution's name and/or description | | delete_solution | Delete a solution (does not delete linked resources — only the grouping) | | link_solution_resources | Link agents, knowledge bases, and/or source connections to a solution | | unlink_solution_resources | Unlink agents, knowledge bases, and/or source connections from a solution | ### Agent AI Assistant Tools All AI assistant tools use a cost-effective model with tool-use support. | Tool | Description | | ---------------------------------------- | ----------------------------------------------------------------- | | generate_step_config | Generate or refine a single step's configuration using AI | | generate_agent_steps | Generate a complete agent workflow from a natural language prompt | | get_ai_conversation_history | View past AI assistant conversation turns for a step | | mark_ai_suggestion | Accept or decline a proposed AI configuration | Prompt Call convention used by MCP AI tools: - Use `{{agent.input}}` for the user's original message - Use `{{input}}` only for previous-step output/context - Place instruction logic in the Prompt Call `system_template` Model lifecycle fields can also be generated and updated through MCP: - Agent-level defaults: `prompt_model_auto_upgrade_strategy`, `prompt_model_auto_rollback_enabled`, `prompt_model_auto_rollback_triggers` - Step-level overrides on `prompt_call` and `extract_data`: `auto_upgrade_strategy`, `auto_rollback_enabled`, `auto_rollback_triggers` Recommended prompt for `generate_step_config`: "Configure this prompt_call step to use cautious auto-upgrade with rollback enabled on governance_block and agent_eval_fail, while keeping temperature low for deterministic output." Recommended prompt for `generate_agent_steps`: "Build an agent that uses model lifecycle defaults: middle_of_road auto-upgrade, rollback enabled, triggers agent_eval_fail + governance_block." ### Solution AI Assistant Tools The solution AI assistants use a **propose-then-accept** workflow: you describe what you want in natural language, the assistant generates a plan with proposed actions, and you review and accept or decline the plan before any changes are made. Destructive actions (deletions) require explicit confirmation. | Tool | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | | generate_source_plan | Generate a plan for creating, updating, or deleting content sources within a solution | | generate_kb_plan | Generate a plan for creating, updating, or deleting knowledge bases within a solution | | generate_solution_plan | Generate a comprehensive plan that can span sources, knowledge bases, and agents | | accept_solution_plan | Accept and execute a previously proposed plan (set confirm_deletions: true for deletions) | | decline_solution_plan | Decline a proposed plan — it will be marked as declined and cannot be executed | ### Governance Tools Governance lets you define policies that evaluate agent and source content for safety, PII, bias, and other concerns. All governance tools require a subscription plan with **governance access** enabled. If your plan does not include governance, these tools will return an error. See the [Governance documentation](https://seclai.com/docs/governance) for a full explanation of policies, scoping, enforcement levels, knowledge base associations, and other concepts. **Policy management:** | Tool | Description | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | list_governance_policy_documents | List available sample policies from the library, optionally filtered by category | | get_governance_policy_document | Get a specific policy document including its full policy text | | list_governance_policies | List governance policies assigned to the account, with optional scope filters | | get_governance_policy | Get a specific account governance policy by ID | | create_governance_policy | Create a new policy from a sample policy or custom text, optionally scoped to an agent, step, or source. Inheritance mode only applies to scoped policies. | | update_governance_policy | Update a policy's enabled status, thresholds, enforcement level, or inheritance mode | | delete_governance_policy | Soft-delete a governance policy | **Knowledge base associations:** | Tool | Description | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | | list_policy_knowledge_bases | List knowledge base associations for a policy, ordered by position | | set_policy_knowledge_bases | Replace all KB associations for a policy (atomic). Rejects circular references. | | get_circular_knowledge_bases | Get KB IDs that would create circular references. Optionally scope to an agent or source. | **Settings and statistics:** | Tool | Description | | -------------------------------------------- | ------------------------------------------------------------------------------- | | get_governance_settings | Get governance settings for a scope (account, agent, or source) | | update_governance_settings | Update governance settings (enabled, review flags, evaluation tier) | | list_governance_settings | List all governance settings, optionally filtered by agent | | get_governance_stats | Get aggregate governance statistics (pass/flag/block counts, unresolved counts) | | get_governance_credit_estimates | Get estimated credit costs per evaluation tier (fast, balanced, thorough) | **Evaluations and testing:** | Tool | Description | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | list_governance_evaluations | List governance evaluations with filtering by verdict, screening point, and date range | | resolve_governance_evaluation | Resolve a flagged or blocked evaluation with an optional note | | bulk_resolve_governance_evaluations | Resolve multiple evaluations at once with an optional shared resolution note | | opt_evaluation_into_review | Promote a test evaluation to the review queue (policy_test → policy_test_review) | | test_governance_policy | Test content against governance policies and see evaluation results | | test_draft_governance_policy | Test content against an unsaved draft policy with optional thresholds and KB associations | **Audit trail and cost estimation:** | Tool | Description | | -------------------------------------------- | --------------------------------------------------------------------------------------- | | list_governance_audit_trail | List all governance policy changes for the account, with optional date and type filters | | list_governance_policy_changes | List the audit trail for a specific governance policy | | get_governance_credit_estimates | Get estimated credit costs per evaluation tier (fast, balanced, thorough) | ### Governance AI Assistant Tools The governance AI assistant uses the same **propose-then-accept** workflow as the solution AI assistant: describe what you want, review the proposed policy changes, then accept or decline. | Tool | Description | | ------------------------------------------ | ---------------------------------------------------------------------- | | generate_governance_plan | Generate a plan for policy changes from a natural language description | | accept_governance_plan | Accept and execute a previously proposed governance plan | | decline_governance_plan | Decline a proposed governance plan — it will be marked as declined | | list_governance_conversations | List recent governance AI assistant conversations (plans, outcomes) | ## Available Resources The server also exposes reference resources that your AI assistant can read for context: | Resource | URI | Description | | ----------------------- | ------------------------------------------------- | --------------------------------------------- | | Agent Definition Schema | seclai://schema/agent-definition | Full schema reference for agent definitions | | String Substitutions | seclai://schema/string-substitutions | All supported string substitution expressions | --- ## Setup The MCP server endpoint is: ``` https://mcp.seclai.com/ ``` It uses the **HTTP** transport and supports **OAuth authentication** (recommended) or API key authentication via the `X-API-Key` header. Most MCP clients support OAuth automatically — just enter the server URL and sign in when prompted. For clients that require manual API key configuration, see the instructions below. ### Claude Desktop Claude Desktop supports OAuth natively. Add the server URL to your config: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "seclai": { "type": "http", "url": "https://mcp.seclai.com/" } } } ``` Restart Claude Desktop. It will prompt you to sign in via your Seclai account.
Alternative: API key authentication If you prefer API key auth, add the header to the config: ```json { "mcpServers": { "seclai": { "type": "http", "url": "https://mcp.seclai.com/", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ```
### Claude Code (CLI) Claude Code supports OAuth natively. Add the server: ```bash claude mcp add seclai \ --transport http \ "https://mcp.seclai.com/" ``` Claude Code will handle OAuth authentication automatically when you first use the server.
Alternative: API key authentication ```bash claude mcp add seclai \ --transport http \ "https://mcp.seclai.com/" \ --header "X-API-Key: YOUR_API_KEY" ``` Or in your project's `.mcp.json`: ```json { "mcpServers": { "seclai": { "type": "http", "url": "https://mcp.seclai.com/", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ```
### Cursor 1. Open Cursor Settings (**Cmd+,** on macOS, **Ctrl+,** on Windows/Linux) 2. Navigate to **MCP** in the sidebar 3. Click **Add new MCP server** 4. Set: - **Name:** `seclai` - **Type:** `http` - **URL:** `https://mcp.seclai.com/` 5. Save Cursor will prompt you to authenticate via OAuth when you first use the server.
Alternative: API key authentication Add your API key header in your project's `.cursor/mcp.json`: ```json { "mcpServers": { "seclai": { "type": "http", "url": "https://mcp.seclai.com/", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ```
### Windsurf Add to your `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "seclai": { "type": "http", "url": "https://mcp.seclai.com/" } } } ``` Windsurf will prompt you to authenticate via OAuth when connecting.
Alternative: API key authentication ```json { "mcpServers": { "seclai": { "type": "http", "url": "https://mcp.seclai.com/", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ```
### Other MCP Clients Any client that supports the **HTTP** MCP transport can connect. Configure it with: - **URL:** `https://mcp.seclai.com/` - **Transport:** HTTP - **Auth:** OAuth (automatic) or `X-API-Key: YOUR_API_KEY` header --- ## Usage Examples Once connected, you can interact with Seclai through natural language. Here are some examples: **List your agents:** > _"Show me all my Seclai agents"_ **Create a new agent:** > _"Create a new Seclai agent called 'Daily News Digest' with a schedule trigger and the summarizer template"_ **Read an agent's definition:** > _"Get the full definition for my Daily News Digest agent"_ **Modify an agent's steps:** > _"Add a retrieval step before the display step in my Daily News Digest agent that searches the news knowledge base"_ **Delete an agent:** > _"Delete the test agent I created earlier"_ **List your knowledge bases:** > _"Show me all my knowledge bases"_ **Create a knowledge base:** > _"Create a knowledge base called 'Podcast Archive' using my podcast sources"_ **Create and manage sources:** > _"Create an RSS feed source for https://example.com/feed.xml"_ > _"Show me all my content sources and change the news feed to poll hourly"_ **Manage solutions:** > _"Create a solution called 'Podcast Pipeline' for my podcast-related agents and sources"_ > _"Link my summarizer agent and podcast knowledge base to the Podcast Pipeline solution"_ **Use the solution AI assistants:** > _"Use the AI assistant to set up RSS feed sources for my three favorite news sites within the News Digest solution"_ > _"Generate a knowledge base plan for my podcast solution that creates a KB from all my podcast sources"_ > _"Generate a comprehensive plan for my solution that adds a new source, creates a KB, and configures an agent"_ > _"Accept the proposed plan"_ or _"Accept the plan and confirm the deletions"_ > _"Decline the proposed plan, I want to try a different approach"_ **View and manage alerts:** > _"Show me any open alerts for my Daily News Digest agent"_ > _"Resolve alert abc123 with a comment that the upstream API is fixed now"_ **Configure alert rules:** > _"Set up an alert that fires after 3 consecutive failures on my Daily News Digest agent"_ > _"Show me all alert configurations for my agent"_ **Use the agent AI assistant to generate configs:** > _"Use the AI assistant to generate a transform step configuration that extracts article titles and URLs"_ > _"Generate a full agent workflow that monitors RSS feeds and sends a daily email summary"_ **Configure evaluation criteria and thresholds:** > _"Create evaluation criteria for step final-answer with prompt 'Check factual accuracy and completeness', pass_threshold 0.75, tier balanced"_ > _"Update criteria abc123 and set pass_threshold to 0.85"_ > _"Test draft evaluation for this step output with pass_threshold 0.8 before saving"_ **Use evaluate_step in a workflow:** > _"Add an evaluate_step after generate-report targeting generate-report with pass_threshold 0.7"_ > _"Add a gate after the evaluate_step so the workflow branches on passed/failed"_ **Review agent AI suggestions:** > _"Show me the AI conversation history for the transform step of my agent"_ > _"Accept the last AI suggestion for my transform step"_ **Manage governance policies:** > _"Provision the default governance policies for my account"_ > _"List my governance policies"_ > _"Create a PII policy scoped to my customer support agent"_ > _"Disable the bias policy and set the content safety policy's block threshold to 0.95"_ > _"Delete the custom policy I created earlier"_ **Governance settings and monitoring:** > _"Show me my governance settings"_ > _"Enable input review for my agent and set the evaluation tier to thorough"_ > _"Show me my governance stats for the last 7 days"_ > _"List any unresolved flagged evaluations"_ > _"Resolve evaluation abc123 — it was a false positive"_ **Test governance policies:** > _"Test the text 'Please send your social security number' against my governance policies"_ **Use the governance AI assistant:** > _"Use the governance assistant to add PII and content safety policies with strict thresholds"_ > _"Accept the proposed governance plan"_ > _"Decline the governance plan, I want different thresholds"_ Your AI assistant will use the MCP tools to perform these actions. It can also read the agent definition schema and string substitutions resources for reference when building definitions. ## Optimistic Locking When updating agent definitions, the MCP server uses optimistic locking to prevent overwriting concurrent changes: 1. Call `get_agent_definition` — the response includes a `change_id` 2. Call `update_agent_definition` with the `expected_change_id` set to the `change_id` from step 1 3. If the definition was modified between steps 1 and 2, you'll get a `conflict` error — re-read and retry Your AI assistant handles this automatically. If you see a conflict error, simply repeat your request and it will re-read the latest definition before applying changes. ## Agent Templates When creating agents, you can specify a template to start with a pre-configured definition: | Template | Description | | ------------------------------------ | ----------------------------------------- | | blank | Empty agent with no steps | | retrieval_example | Demonstrates knowledge base retrieval | | simple_qa | Basic question-answering agent | | summarizer | Summarizes content from sources | | json_extractor | Extracts structured data from content | | content_change_notifier | Monitors sources for changes and notifies | | scheduled_report | Generates reports on a schedule | | webhook_pipeline | Processes incoming webhook data | --- ## Rate Limits MCP calls are rate-limited per account based on your subscription plan. Each tool call counts as one MCP call. The limit is enforced as a sliding window per minute. | Plan | MCP Calls per Minute | | ------- | -------------------- | | Starter | 30 | | Team | 75 | | Pro | 300 | When you exceed the limit, tool calls will return an error with a `retry_after` value indicating how many seconds to wait before retrying. Most AI assistants will handle this automatically. If you need higher limits, contact us about an Enterprise plan or request a per-account override. --- > **Streaming agents via MCP:** Agents with a `streaming_result` step work normally when run via MCP — the agent executes and you receive the final output. However, real-time token streaming (`stream_token` / `stream_end` SSE events) is only available via the [REST API streaming endpoint](https://seclai.com/docs/agent-streaming). MCP runs always return the complete output after the run finishes. --- ## Troubleshooting **"Invalid API key" error** - Verify your API key is correct and hasn't been archived or deleted - Ensure your account is in good standing (not suspended or delinquent) - Confirm your plan includes API access - MCP requires user-scoped API keys — if you get a "user-scoped" error, re-create your key **"MCP requires a user-scoped API key" error** - Your API key was created before user-scoping was introduced - Create a new API key from your account settings — new keys are automatically user-scoped - Delete or archive your old key to avoid confusion **"Rate limit exceeded" error** - Wait the number of seconds indicated in the error before retrying - Consider upgrading your plan if you consistently hit the limit - Check that you aren't running multiple MCP clients with the same key simultaneously **Tools not appearing in your client** - Restart your MCP client after configuration changes - Verify the URL is exactly `https://mcp.seclai.com/` - Check that you're using the `http` transport type (not `sse` or `stdio`) - Look at your client's MCP logs for connection errors **"Missing X-API-Key header" error** - Ensure the `X-API-Key` header is configured in your MCP client settings - Some clients require restarting after adding headers **Conflict errors when updating definitions** - This means the definition was changed since you last read it - Simply retry your request — your AI assistant will re-read the latest definition and try again **OAuth sign-in page doesn't appear** - Confirm your MCP client supports OAuth (Claude Desktop, Claude Code, Cursor, and Windsurf all do) - If your client doesn't support OAuth, fall back to API key authentication - Check your client's MCP logs for connection or redirect errors **OAuth token expired** - Most clients refresh tokens automatically. If you see repeated 401 errors, disconnect and reconnect the server to re-authenticate - Clearing your client's MCP credential cache may also help --- **Next steps:** - [API Keys](https://seclai.com/docs/api-keys) — Create and manage API keys - [Agents](https://seclai.com/docs/agents) — Learn about agent concepts - [Agent Steps](https://seclai.com/docs/agent-steps) — Reference for all step types - [API Introduction](https://seclai.com/docs/api-introduction) — REST API overview