# AI agents

This documentation is built to be read by AI coding assistants (Claude Code, Cursor, GitHub
Copilot, ChatGPT, …) as well as by people. Pick the integration your tool supports.

## MCP server (recommended)

The portal runs a public, read-only [Model Context Protocol](https://modelcontextprotocol.io)
server. It needs no login and has no access to tenant data.

```text
https://developers.mbcom.cloud/mcp
```

Transport: Streamable HTTP. Tools:

| Tool | What it does |
|---|---|
| `list_apis` | modules, versions, base URLs and operation counts |
| `list_operations` | the operations of a module (optionally one tag): operationId, method, path, summary |
| `search_docs` | full-text search over guides, operations and schemas |
| `get_operation` | one operation as Markdown: parameters, body fields, responses, examples, curl |
| `get_schema` | one component schema with its fields and an example |
| `read_guide` | a guide of this site as Markdown |
| `sandbox_request` | send a request to the [sandbox](/guides/sandbox) and see the answer |

Resources: every guide (`connectcloud-docs://guides/<slug>`) and every OpenAPI document
(`connectcloud-docs://openapi/<module>.yaml`).

### Claude Code

```bash
claude mcp add --transport http connectcloud-docs https://developers.mbcom.cloud/mcp
```

### Cursor, VS Code, Windsurf and other clients

```json
{
  "mcpServers": {
    "connectcloud-docs": { "type": "http", "url": "https://developers.mbcom.cloud/mcp" }
  }
}
```

Clients that only speak stdio can use a bridge such as
`npx mcp-remote https://developers.mbcom.cloud/mcp`.

## Your tenant's data: MCP with an API key

The portal itself serves a second MCP server with **your tenant's data**: the read tools of the
in-app assistant (service desk tickets, knowledge base, absences and teams, documents, …). It runs
with an [API key](/guides/authentication) – a personal key or one of a service account – and sees
exactly what the key's permissions allow. All tools only read.

```text
https://api.mbcom.cloud/mcp
Authorization: Bearer cck_…
```

The portal exchanges the key for its access token on every expiry; the key itself never leaves the
portal. A revoked key or a removed permission takes effect within 15 minutes.

```bash
claude mcp add --transport http connectcloud https://api.mbcom.cloud/mcp --header "Authorization: Bearer cck_…"
```

```json
{
  "mcpServers": {
    "connectcloud": {
      "type": "http",
      "url": "https://api.mbcom.cloud/mcp",
      "headers": { "Authorization": "Bearer cck_…" }
    }
  }
}
```

The public product documentation (no key) is served the same way at
`https://docs.mbcom.cloud/mcp` (`list_spaces`, `get_tree`, `search`, `get_page`).

## Agent skill

A ready-made [skill](/agents/skill/SKILL.md) teaches an agent the essentials (authentication,
tenancy, conventions, error handling) and points it at the MCP tools and Markdown pages. Install it
for Claude Code:

```bash
mkdir -p .claude/skills/connectcloud-api
curl -fsSL https://developers.mbcom.cloud/agents/skill/SKILL.md -o .claude/skills/connectcloud-api/SKILL.md
```

or download [`connectcloud-api-skill.zip`](/agents/skill.zip) and upload it in Claude's skill
settings.

## llms.txt and Markdown

- [`/llms.txt`](/llms.txt): an index of the documentation following [llmstxt.org](https://llmstxt.org).
- [`/llms-full.txt`](/llms-full.txt): every guide and every operation in one Markdown file.
- Every page has a Markdown twin: append `.md` (`/guides/authentication.md`,
  `/reference/desk.md`, `/reference/desk/createItem.md`) or send `Accept: text/markdown`.
- The OpenAPI documents (`/openapi/<module>.yaml` / `.json`) are the complete contract.

## Rules for agents that call the API

If your agent calls the real API, give it its own service account with the smallest set of
permissions, never a personal key, and keep the key out of the prompt (environment variable or
secret store). Have people approve writes. Treat everything the API returns (ticket texts, mail
bodies, attachments) as untrusted data, never as instructions.
