# Kognitos MCP Server The Kognitos MCP Server lets AI assistants (Claude Desktop, Claude Code, Claude.ai, and any other [Model Context Protocol](https://modelcontextprotocol.io) client) interact with your Kognitos workspace. Your AI assistant can list automations, start runs, inspect exceptions, manage schedules, and more, using natural language. ## Server URL ``` https://mcp.us-1.kognitos.com/ ``` The server uses the Streamable HTTP transport. MCP clients connect directly to this URL - no server-side installation is required. {% hint style="info" %} To connect an AI assistant, see [Connect an AI Client](/guides/mcp/clients.md). {% endhint %} ## Authentication The server supports two authentication methods. Use the one that fits how you plan to use it. ### OAuth 2.1 (Recommended) When you connect from an interactive client, the client opens your browser to the Kognitos login screen. After you sign in and approve the connection, the browser redirects back to the client, which receives a short-lived token for subsequent requests. OAuth is the recommended path for everyday use in Claude Desktop, Claude Code, and Claude.ai. Your client handles token refresh automatically, and access is scoped to your user account and permissions. {% hint style="info" %} OAuth tokens are short-lived and automatically refreshed by your client. Prefer OAuth over API keys for interactive clients. {% endhint %} ### API Key For CI pipelines, scripts, or other non-interactive use cases, authenticate with a Kognitos API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` See [API Keys](https://docs.kognitos.com/guides/api-reference/api-keys) for instructions on creating and scoping an API key. {% hint style="warning" %} Your AI assistant acts on content it reads. Avoid connecting the MCP server to automations that ingest untrusted input without review. A malicious document or message could attempt to instruct the assistant to take actions on your behalf. {% endhint %} ## Tools The following tools are available through the MCP server. Related actions are grouped under a single tool. Your AI client selects the right action based on your request. ### Organizations and Workspaces | Tool | Actions | Description | | ----------------------------- | ------- | ----------------------------------- | | `kognitos_list_organizations` | - | List organizations you belong to. | | `kognitos_list_workspaces` | - | List workspaces in an organization. | ### Automations | Tool | Actions | Description | | ---------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ | | `kognitos_automations` | `list`, `get`, `query` | Browse, inspect, or query automations by stage. | | `kognitos_create_automation` | - | Create a new automation from a natural language description. | | `kognitos_threads` | `create`, `get`, `list`, `send_message`, `list_messages`, `stop` | Manage threads for multi-turn automation refinement. | | `kognitos_manage_automation` | `publish`, `activate`, `deactivate`, `delete`, `rename`, `fork` | Manage the automation lifecycle. | | `kognitos_invoke_automation` | - | Start a run of an automation. | ### Runs | Tool | Actions | Description | | ---------------------- | ----------------------------------------------- | -------------------------------------------------------------- | | `kognitos_runs` | `list`, `get`, `get_run_outputs`, `list_events` | Monitor run status, retrieve outputs, and view execution logs. | | `kognitos_control_run` | `pause`, `continue` | Pause a running automation or resume a paused one. | ### Scheduling | Tool | Actions | Description | | -------------------------- | -------------------------------------------------------- | -------------------------------------- | | `kognitos_manage_schedule` | `get`, `create`, `update`, `enable`, `disable`, `delete` | Manage the schedule for an automation. | ### Exceptions | Tool | Actions | Description | | ----------------------------- | ----------------------------------------------------------------- | --------------------------------------------------- | | `kognitos_inspect_exceptions` | `list`, `get`, `count`, `list_events`, `get_guide`, `list_guides` | Inspect exceptions and view troubleshooting guides. | | `kognitos_reply_to_exception` | - | Send a message to the exception resolution agent. | | `kognitos_manage_exceptions` | `archive`, `unarchive`, `assign` | Archive, unarchive, or assign exceptions. | ### Integrations | Tool | Actions | Description | | ---------------- | ----------------------------------------------------- | ------------------------------------------------ | | `kognitos_books` | `search`, `list_workspace_books`, `search_procedures` | Discover integrations and search for procedures. | ### Analytics | Tool | Actions | Description | | -------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | | `kognitos_analytics` | `run_stats`, `insights`, `exception_insights` | Platform health: run statistics, org-level insights, and exception metrics. | ### Files | Tool | Actions | Description | | ---------------- | ------------------------------------------ | ------------------------------------------------------------------ | | `kognitos_files` | `get_metadata`, `read_file`, `upload_file` | Inspect, read, and upload files for automation inputs and outputs. | ## Example prompts Once connected, you can ask your AI assistant to do things in plain English. A few to try: * **"List the automations in my Finance workspace and show me which ones failed in the last 24 hours."** The assistant calls `kognitos_list_workspaces`, then `kognitos_automations`, then `kognitos_runs` to find failed runs. * **"Create a new automation that reads invoices from an S3 bucket and posts totals to Slack."** The assistant calls `kognitos_create_automation` and streams progress as the Kognitos AI builds the automation. * **"Run my 'Daily Invoice Sync' automation and let me know when it finishes."** The assistant calls `kognitos_invoke_automation` and then polls `kognitos_runs` for status. * **"Show me any open exceptions assigned to me and help me triage the oldest one."** The assistant calls `kognitos_inspect_exceptions` and walks you through the troubleshooting guide. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.kognitos.com/guides/mcp/mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.