From c8e8059b0c98a40e40104725abb6af70644f31f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Tue, 11 Aug 2026 17:44:25 +0200 Subject: [PATCH 1/6] docs: add Kosli MCP server integration page --- config/navigation.json | 3 +- integrations/mcp_server.md | 128 +++++++++++++++++++++++++++++ understand_kosli/ai_docs_access.md | 4 + 3 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 integrations/mcp_server.md diff --git a/config/navigation.json b/config/navigation.json index e2f857e..e680d77 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -177,7 +177,8 @@ "integrations/ci_cd", "integrations/slack", "integrations/launchdarkly", - "integrations/sonar" + "integrations/sonar", + "integrations/mcp_server" ] } ] diff --git a/integrations/mcp_server.md b/integrations/mcp_server.md new file mode 100644 index 0000000..a8094bf --- /dev/null +++ b/integrations/mcp_server.md @@ -0,0 +1,128 @@ +--- +title: MCP server +description: Connect AI assistants such as Claude Code and Claude Desktop to the Kosli API using the Model Context Protocol. +tag: "BETA" +--- + +The Kosli MCP server is a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the Kosli API to AI assistants. Once it is connected, you can ask questions like _"which environments are non-compliant, and why?"_ and the assistant calls the relevant Kosli endpoints to answer. + +It is published from [`kosli-dev/mcp-server`](https://github.com/kosli-dev/mcp-server) and distributed as an npm package (`@kosli/mcp-server`) and as a `.mcpb` bundle for Claude Desktop. + + +The Kosli MCP server is in beta. Tool names, parameters, and behavior may change between releases. Pin a version if you need stability: `npx -y @kosli/mcp-server@0.5.0`. + + + +This server reads the data in your Kosli organization. To let an AI assistant search this documentation instead, see [AI access to these docs](/understand_kosli/ai_docs_access). The two are complementary, and you can connect both. + + +## How it works + +Rather than ship one tool per Kosli endpoint, the server generates a catalog of actions from Kosli's OpenAPI spec and exposes three generic tools: + +| Tool | Purpose | +|------|---------| +| `search_actions` | Fuzzy-search the catalog for relevant actions by natural-language query. | +| `execute_read_action` | Invoke any `GET` action by ID. Auto-allowed in MCP clients. | +| `execute_write_action` | Invoke any `POST`, `PUT`, `PATCH`, or `DELETE` action by ID. Gated behind user approval. | + +The assistant first calls `search_actions` to find the right action ID and its parameter schema, then calls `execute_read_action` or `execute_write_action` with that ID. Both execute tools accept an optional `fields` array that limits the response to specific top-level fields, which keeps responses small and token usage down. + +The `org` path parameter defaults to `KOSLI_ORG` when it is not supplied. + + +`execute_write_action` creates, modifies, and deletes real resources in your Kosli organization. MCP clients gate these calls behind an approval prompt, and that prompt is the only checkpoint before the call is made. An assistant may choose the wrong action, or the right action with the wrong parameters, so read the action ID and parameters before approving. Treat deletions and anything touching service accounts or API keys with particular care. + + +## Prerequisites + +- Node.js v22 or higher +- A Kosli API key. Use a [personal API key](/user/personal_api_keys) when you run the server on your own machine, or a [service account key](/administration/authentication/service_accounts) for automation. +- An MCP-capable client, such as Claude Code or Claude Desktop + +## Install + + + + Run this from your project directory, or add `--scope user` to install it globally: + + ```bash + claude mcp add kosli \ + -e KOSLI_API_TOKEN=your-token \ + -e KOSLI_ORG=your-org \ + -- npx -y @kosli/mcp-server + ``` + + + Download the latest `.mcpb` file from the [releases page](https://github.com/kosli-dev/mcp-server/releases) and drag it into Claude Desktop, or double-click it to install. Claude Desktop prompts you for your API key and organization, and stores the secrets in your operating system keychain. + + This is the recommended method for Claude Desktop. + + + Extensions installed from a file show an "unverified by Anthropic" warning and do not auto-update, so you need to download and reinstall new versions manually. Both limitations go away once the extension is listed in Anthropic's [Connectors Directory](https://claude.com/docs/connectors/building/submission). + + + + Add the following to `claude_desktop_config.json`, which you can open from **Settings → Developer → Edit Config**: + + ```json + { + "mcpServers": { + "kosli": { + "command": "npx", + "args": ["-y", "@kosli/mcp-server"], + "env": { + "KOSLI_API_TOKEN": "your-token", + "KOSLI_ORG": "your-org" + } + } + } + } + ``` + + This method auto-updates through `npx` on each restart, but stores your API key in plain text. + + + The server communicates over stdio. Point any MCP-capable client at the package with `npx -y @kosli/mcp-server` and set the environment variables below. + + + +## Configuration + +The server reads its configuration from environment variables. + +| Variable | Required | Default | Notes | +|----------|----------|---------|-------| +| `KOSLI_API_TOKEN` | yes | - | `KOSLI_API_KEY` is accepted as a fallback. | +| `KOSLI_ORG` | yes | - | Default org, used when an action does not supply an `org` path parameter. | +| `KOSLI_BASE_URL` | no | `https://app.kosli.com` | Use `https://app.us.kosli.com` for US, or your own single-tenant endpoint. | + +## Example prompts + +These prompts only read data, so they run without an approval step. Replace the environment, flow, and trail names with your own. + +### Environments and compliance + +- "Which of my environments are non-compliant, and why?" +- "What is running in `prod-aws` right now?" +- "Has anything changed in `prod-aws` since yesterday?" + +The assistant answers these from [environment snapshots](/getting_started/environments), so it can report both the current state and the reasons an environment is not compliant. + +### Audit and evidence + +- "List every deployment to `prod-aws` in the last 30 days." +- "What attestations are on trail `release-456` in flow `my-release`?" +- "Which artifacts running in `prod-aws` have no security scan attestation?" + +The last prompt takes several tool calls, because the assistant has to list what is running and then check the [attestations](/getting_started/attestations) on each artifact. Expect it to be slower than a single lookup, and check the artifact list it worked from before relying on the answer. + +## Limitations + +- The action catalog is generated from a snapshot of the OpenAPI spec. New endpoints become available when the catalog is regenerated and a new version of the package is published. +- Ambiguous questions may take several `search_actions` calls before the assistant settles on the right action. +- Responses are whatever the Kosli API returns. Large responses consume a lot of context, so ask for specific fields when you can. + +## Feedback + +The server is in beta and we want to hear how it works for you. Email [support@kosli.com](mailto:support@kosli.com) or open an issue in [`kosli-dev/mcp-server`](https://github.com/kosli-dev/mcp-server/issues). diff --git a/understand_kosli/ai_docs_access.md b/understand_kosli/ai_docs_access.md index ef7a153..d2fcb1f 100644 --- a/understand_kosli/ai_docs_access.md +++ b/understand_kosli/ai_docs_access.md @@ -5,6 +5,10 @@ description: 'Use MCP servers, skill.md, and llms.txt to let AI tools read and s Kosli documentation supports AI-friendly access through three mechanisms: an **MCP server** for semantic search, a **skill.md** endpoint that teaches AI assistants how the docs are organized, and **llms.txt** files that provide full documentation content. These let you query Kosli documentation directly from AI coding assistants like Cursor, Claude Code, Windsurf, VS Code with Copilot, and others. + +Everything on this page covers access to the documentation. To let an AI assistant query the data in your own Kosli organization, see the [Kosli MCP server](/integrations/mcp_server). + + ## MCP server The Model Context Protocol (MCP) server lets AI tools search Kosli documentation semantically. Instead of copy-pasting docs into a chat window, you connect your AI assistant to the MCP endpoint and it can search the docs on its own. From 4aa65026fc23c338c05725fed7d898280ee4df43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 13 Aug 2026 08:22:09 +0200 Subject: [PATCH 2/6] docs: clarify execute_* tools and consolidate org default --- integrations/mcp_server.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/integrations/mcp_server.md b/integrations/mcp_server.md index a8094bf..e81ad13 100644 --- a/integrations/mcp_server.md +++ b/integrations/mcp_server.md @@ -26,9 +26,7 @@ Rather than ship one tool per Kosli endpoint, the server generates a catalog of | `execute_read_action` | Invoke any `GET` action by ID. Auto-allowed in MCP clients. | | `execute_write_action` | Invoke any `POST`, `PUT`, `PATCH`, or `DELETE` action by ID. Gated behind user approval. | -The assistant first calls `search_actions` to find the right action ID and its parameter schema, then calls `execute_read_action` or `execute_write_action` with that ID. Both execute tools accept an optional `fields` array that limits the response to specific top-level fields, which keeps responses small and token usage down. - -The `org` path parameter defaults to `KOSLI_ORG` when it is not supplied. +The assistant first calls `search_actions` to find the right action ID and its parameter schema, then calls `execute_read_action` or `execute_write_action` with that ID. Both `execute_*` tools accept an optional `fields` array that limits the response to specific top-level fields, which keeps responses small and token usage down. `execute_write_action` creates, modifies, and deletes real resources in your Kosli organization. MCP clients gate these calls behind an approval prompt, and that prompt is the only checkpoint before the call is made. An assistant may choose the wrong action, or the right action with the wrong parameters, so read the action ID and parameters before approving. Treat deletions and anything touching service accounts or API keys with particular care. @@ -94,7 +92,7 @@ The server reads its configuration from environment variables. | Variable | Required | Default | Notes | |----------|----------|---------|-------| | `KOSLI_API_TOKEN` | yes | - | `KOSLI_API_KEY` is accepted as a fallback. | -| `KOSLI_ORG` | yes | - | Default org, used when an action does not supply an `org` path parameter. | +| `KOSLI_ORG` | yes | - | Default org. Used as the `org` path parameter when an action does not supply one. | | `KOSLI_BASE_URL` | no | `https://app.kosli.com` | Use `https://app.us.kosli.com` for US, or your own single-tenant endpoint. | ## Example prompts From 5ec87fae3b6443c11d45d7581b2fa348fdfc13f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 13 Aug 2026 08:48:25 +0200 Subject: [PATCH 3/6] docs: trim mcp server tool mechanics to what readers act on --- integrations/mcp_server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/mcp_server.md b/integrations/mcp_server.md index e81ad13..7a47dbe 100644 --- a/integrations/mcp_server.md +++ b/integrations/mcp_server.md @@ -26,7 +26,7 @@ Rather than ship one tool per Kosli endpoint, the server generates a catalog of | `execute_read_action` | Invoke any `GET` action by ID. Auto-allowed in MCP clients. | | `execute_write_action` | Invoke any `POST`, `PUT`, `PATCH`, or `DELETE` action by ID. Gated behind user approval. | -The assistant first calls `search_actions` to find the right action ID and its parameter schema, then calls `execute_read_action` or `execute_write_action` with that ID. Both `execute_*` tools accept an optional `fields` array that limits the response to specific top-level fields, which keeps responses small and token usage down. +These are the tool names your client shows as the assistant works, and the name in the prompt when it asks you to approve a write. `execute_write_action` creates, modifies, and deletes real resources in your Kosli organization. MCP clients gate these calls behind an approval prompt, and that prompt is the only checkpoint before the call is made. An assistant may choose the wrong action, or the right action with the wrong parameters, so read the action ID and parameters before approving. Treat deletions and anything touching service accounts or API keys with particular care. From ebc82ad40bc6a71e29be9d3a95612e154e0f4f4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 13 Aug 2026 08:56:51 +0200 Subject: [PATCH 4/6] docs: clarify node requirement applies to mcpb installs --- integrations/mcp_server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/mcp_server.md b/integrations/mcp_server.md index 7a47dbe..515da78 100644 --- a/integrations/mcp_server.md +++ b/integrations/mcp_server.md @@ -34,7 +34,7 @@ These are the tool names your client shows as the assistant works, and the name ## Prerequisites -- Node.js v22 or higher +- Node.js v22 or higher. This applies to every install method, including the `.mcpb` bundle, which declares the same requirement in its extension manifest. - A Kosli API key. Use a [personal API key](/user/personal_api_keys) when you run the server on your own machine, or a [service account key](/administration/authentication/service_accounts) for automation. - An MCP-capable client, such as Claude Code or Claude Desktop From 06cb708c239e01c1b440ef9f57a9d50b49f2a67f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 13 Aug 2026 09:04:20 +0200 Subject: [PATCH 5/6] fix: mcpb installs do not require node, claude desktop bundles it --- integrations/mcp_server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/mcp_server.md b/integrations/mcp_server.md index 515da78..ac550cb 100644 --- a/integrations/mcp_server.md +++ b/integrations/mcp_server.md @@ -34,7 +34,7 @@ These are the tool names your client shows as the assistant works, and the name ## Prerequisites -- Node.js v22 or higher. This applies to every install method, including the `.mcpb` bundle, which declares the same requirement in its extension manifest. +- Node.js v22 or higher, for the `npx`-based install methods. You do not need it for the `.mcpb` bundle, because Claude Desktop ships its own Node runtime. - A Kosli API key. Use a [personal API key](/user/personal_api_keys) when you run the server on your own machine, or a [service account key](/administration/authentication/service_accounts) for automation. - An MCP-capable client, such as Claude Code or Claude Desktop From eba56405c61c7e436bc3b7f323b3613c49d2c0d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 13 Aug 2026 09:30:03 +0200 Subject: [PATCH 6/6] docs: add missing period in mcp server prerequisites --- integrations/mcp_server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/mcp_server.md b/integrations/mcp_server.md index ac550cb..6189aac 100644 --- a/integrations/mcp_server.md +++ b/integrations/mcp_server.md @@ -36,7 +36,7 @@ These are the tool names your client shows as the assistant works, and the name - Node.js v22 or higher, for the `npx`-based install methods. You do not need it for the `.mcpb` bundle, because Claude Desktop ships its own Node runtime. - A Kosli API key. Use a [personal API key](/user/personal_api_keys) when you run the server on your own machine, or a [service account key](/administration/authentication/service_accounts) for automation. -- An MCP-capable client, such as Claude Code or Claude Desktop +- An MCP-capable client, such as Claude Code or Claude Desktop. ## Install