# MCP server · DameDoklad docs

> Connect Claude, ChatGPT or Cursor to your accounting with the Model Context Protocol, by OAuth 2.1 sign-in or an API key.

Source: https://damedoklad.cz/en/docs/mcp/

# MCP server

Connect Claude, ChatGPT or Cursor to your accounting with the Model Context Protocol, by OAuth 2.1 sign-in or an API key.

The MCP server connects AI assistants to your accounting through the [Model Context Protocol](https://modelcontextprotocol.io). You ask in your own words and the assistant calls the same operations the app uses.

|  |  |
| --- | --- |
| **Address** | `https://api.damedoklad.cz/mcp` |
| **Transport** | Streamable HTTP, stateless, `POST` only |
| **Tools** | Each `/v1` operation is one tool; see the [tool list](/en/docs/mcp/tools/) |
| **Sign-in** | OAuth 2.1 with dynamic client registration, or an API key |

**OAuth or an API key**

The server supports OAuth 2.1 sign-in. A client that supports it sends you to sign in to DameDoklad, and you need no key. Scripts and tools without a browser use an API key in the Authorization header.

## Signing in with OAuth

This is the way for Claude, ChatGPT and other clients that open a browser. You enter only the address above. The client registers itself, sends you to sign in to DameDoklad, and you choose:

-   **which companies** the connection may reach, and
-   **whether it may write** (`full`) or only read (`read`).

You see and revoke connected apps in **Settings > API and MCP**. You need no plan with API keys for this.

For client developers, the details are:

|  |  |
| --- | --- |
| Discovery | `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server` |
| Registration | `POST /oauth/register` (RFC 7591), and client ID metadata documents |
| Flow | Authorization code with PKCE `S256`; public clients use `none` |
| Scopes | `read` and `full` |
| Lifetimes | Access token 15 minutes, refresh token 60 days |

An unauthenticated request gets a `401` with a `WWW-Authenticate` header that points to the discovery document.

## Signing in with an API key

For scripts and tools without a browser. Create a key in **Settings > API and MCP**; see [Sign-in and API keys](/en/docs/authentication/). A key belongs to one company and sets the scope:

```text
Authorization: Bearer secret_…
```

## Claude

In **Claude** on the web and in the desktop app, add a custom connector under **Settings > Connectors** with the address above. It signs in with OAuth.

In **Claude Code**, one command is enough, and it signs in with OAuth the first time you use the server:

```bash
claude mcp add --transport http damedoklad https://api.damedoklad.cz/mcp
```

To use an API key there instead, add `--header "Authorization: Bearer $DAMEDOKLAD_API_KEY"`.

## ChatGPT

In ChatGPT, remote MCP servers are added in developer mode in settings. Enter the address above and sign in with OAuth.

## Cursor

Add the server to `~/.cursor/mcp.json` or to `.cursor/mcp.json` in a project. Cursor signs in with OAuth; with an API key, load it from an environment variable so it stays out of your repository:

```json
{
  "mcpServers": {
    "damedoklad": {
      "url": "https://api.damedoklad.cz/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DAMEDOKLAD_API_KEY}"
      }
    }
  }
}
```

## Other clients

Any client that supports a remote server over Streamable HTTP connects the same way: with OAuth discovery, or with the address and an `Authorization` header.

## Several companies

An OAuth connection can reach every company you allowed it. `get-current-workspace` says which one is active, and `switch-workspace` changes it. An API key always stays in its one company.

## Fewer tools

Some clients limit the number of tools. Use the `tools` parameter to pick only some groups:

```text
https://api.damedoklad.cz/mcp?tools=invoices,contacts
```

The `list-tool-groups` tool prints the group names, and they are in the [tool list](/en/docs/mcp/tools/) too. The `get-current-workspace` and `list-tool-groups` tools are always available.

To offer only reading tools on any connection, add `?read_only=1` or the `X-MCP-Readonly: 1` header. A connection with the `read` scope never sees writing tools.

## What to watch out for

Issuing a document and posting have legal effect. The assistant should confirm them with you.

The `confirm-payment-order-send` and `confirm-filing-submission` tools send real money and real filings. A connection sees them only with the [permission to send](/en/docs/authentication/), and they work only when the owner turned that on for the company, within its limits. Without that, the assistant prepares the order or filing and you confirm it in the app.

Text in documents and e-mails is written by strangers and can try to steer an agent. Give the permission to send only to an agent you fully trust, and not to one that reads outside documents unattended.

Irreversible tools are labelled and MCP clients ask before running them. Review the proposal before you approve it. Posted entries are never edited, only reversed with a counter-entry.

Amounts in tools are whole numbers of haléře and dates are `YYYY-MM-DD`; see [API conventions](/en/docs/conventions/).

## Try it

-   “Which company are you connected to?”
-   “Which invoices are more than 30 days overdue?”
-   “Draft an invoice for Kavárna Modrá for CZK 18,400 without VAT, at the 12% rate.”