> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> What the MCP server is, endpoints, supported clients, and versioning.

The Concierca AI MCP server exposes your entire Concierca AI workspace as a set of typed tools over the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-capable AI client — Claude (web/desktop), ChatGPT, Claude Code, or your own agent runtime — can connect and:

* **Read** agents, missions, runs, knowledge, memories, skills, inbox items, approvals and your business data tables.
* **Write** (when enabled): create and update agents, run missions, save memories and knowledge, upsert data rows, resolve approvals, and more.

Every tool call runs **server-side as the user who owns the credential**. All reads are scoped to exactly what that user can see in the Concierca AI app — tenant, workspace, department and user layer. There is no way to widen visibility through the API.

## Endpoints

| Endpoint                                           | Purpose                                                                                              |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `https://app.concierca.ch/api/mcp/v1`              | **Main control-plane MCP server** (canonical URL). Streamable HTTP transport, JSON-RPC 2.0.          |
| `https://app.concierca.ch/api/mcp/watchinside`     | Standalone **Vertical** (market intelligence) MCP server — see [Vertical](/for-agents/vertical).     |
| `https://app.concierca.ch/api/mcp/vertical/<slug>` | Generic per-vertical endpoint (one per vertical connection).                                         |
| `https://app.concierca.ch/api/mcp/oauth/*`         | OAuth 2.1 endpoints (authorize, token, dynamic client registration) — used automatically by clients. |

A `GET` on the main endpoint returns a health object: `{ ok, mcp_protocol_version, server, version }`.

* MCP protocol version: `2025-03-26`
* Transport: HTTP POST with JSON-RPC 2.0 bodies (`initialize`, `tools/list`, `tools/call`)

Vertical tools are also **federated into the main server**: when your account has a vertical connection, its tools appear on `/api/mcp/v1` under a namespaced name (`vertical__vertical_card`, `vertical__vertical_search`, …). You do not need a second connector for them.

## Connecting a client

### Claude (claude.ai / Claude desktop)

1. Settings → Connectors → *Add custom connector*.
2. Enter the URL `https://app.concierca.ch/api/mcp/v1`.
3. Claude opens the Concierca AI consent screen — sign in with your Concierca AI account and approve.
4. Done. Claude lists the tools your account is entitled to.

Claude uses the OAuth flow (no key handling on your side). See [Authentication](/for-agents/authentication).

### ChatGPT (connectors / custom GPT actions)

Same URL and OAuth flow. **Known client quirk:** ChatGPT caches the tool list when the connector is created and does not refresh it on reconnect. If tools were added or renamed on the server (compare `whoami.registry_version`), **delete the connector and create it again** to pick up the current tool list.

### API-key clients (Claude Code, scripts, custom runtimes)

Create a personal API key in the app (Settings → MCP Access), then send it on every request:

```text theme={null}
POST https://app.concierca.ch/api/mcp/v1
X-API-KEY: <your key>
```

`Authorization: Bearer <token>` is also accepted (this is what OAuth tokens use).

## First calls in every session

1. `whoami` — identity, role, tenant, departments, and the exact tool surface of this credential.
2. `get_context` — the Operating-Manual context block (high-importance memories + knowledge) that the in-app chat auto-injects. Over MCP it is pull-only; call it once at session start.
3. `guardrails_get` — the always-load governance rules. Also pull-only over MCP; fetch once and honor them.

## Versioning

* The server does **not** push `listChanged` notifications. Clients freeze the tool list at connect time.
* `whoami` returns `registry_version`, a stable fingerprint of the advertised tool surface. If it differs from the value at connect time, reconnect the client to load the current tool list (ChatGPT: delete + recreate the connector).
* Renamed tools keep their **old names as permanent aliases** — existing keys and clients never break. `tools/list` advertises only the canonical names (see [Conventions](/for-agents/conventions)).