# SimpleForms MCP — setup guide for AI assistants

> This file is addressed to you, the AI assistant. The user gave it to you so that
> you connect them to the SimpleForms MCP server. Guide the user step by step,
> ask one question at a time, and adapt commands to their client and OS.
>
> **Language:** always talk to the user in the language they write in.
> If unclear, use Russian. The SimpleForms interface is in Russian: quote
> UI labels exactly as written below (in «»), and add a translation in brackets
> only if the user speaks another language.

## Server parameters

| Parameter | Value |
|---|---|
| Server name | `sf` (any short name is fine) |
| URL | `https://api.simpleforms.ru/mcp` |
| Transport | Streamable HTTP |
| Auth | exactly one HTTP header `X-API-Key: <personal key>` |

This URL is for the production environment. For staging or another installation,
ask the administrator for that environment's Public API `/mcp` URL; the cabinet
URL is not an MCP endpoint.

Important:

- The key is sent **only** in the `X-API-Key` header. Not `Authorization`, not `Bearer`, not OAuth.
- It is a personal SimpleForms key — not an OpenAI, Anthropic, Yandex or Sber key.
- The client must support remote MCP servers over HTTP **and** custom headers.
  If the client supports only stdio — use the `mcp-remote` bridge (see below).
  If the client supports only OAuth — a direct connection is impossible; say so honestly.

## Security rules (mandatory)

1. **Never ask the user to paste the key into the chat** and never print it.
   If the user pastes it anyway, warn them to regenerate it («Создать новый»
   in the cabinet) after setup.
2. Store the key in the `SIMPLEFORMS_MCP_API_KEY` environment variable, the OS
   secret store, or a protected field in the client settings. Never write it into
   project files that may end up in git, and never pass it as a command-line
   argument that stays in shell history.
3. The first check is read-only. Do not create, copy or modify templates until
   the user explicitly asks.

## Step 1. Identify the client

Ask which application the user works in, unless it is obvious from context.
If you are that client and can change your own configuration, offer to do it
for the user — but let the user enter the key themselves.

## Step 2. Help get the key

Explain step by step:

1. Log in to the SimpleForms cabinet: <https://i.simpleforms.ru>.
2. Click your e-mail in the top right corner (next to «Помощь» [Help] and «Выход» [Log out]).
   The «Моя учетная запись» [My account] window opens, showing roles, name, company and time zone.
3. At the bottom of the window, in the «API-ключ MCP» [MCP API key] row, click «Управлять» [Manage]
   (it may have a "new" badge).
4. If a key exists — click «Копировать» [Copy]. If not — click «Создать новый» [Create new]
   and copy the result.

Warn the user: «Создать новый» with an existing key **revokes** the old one —
all existing connections stop working and must be updated.
If the key leaked — «Отозвать» [Revoke], then «Создать новый».

If there is no «API-ключ MCP» row, the user needs permissions to view and edit
templates, and the company must have API access enabled. Send them to their
company's SimpleForms administrator.

## Step 3. Configure the client

Check the current configuration format of the user's client. The examples below
show the required URL, transport and header, but client-specific field names and
secret-substitution rules must be verified for the installed version.

### Claude Code

Use the client's documented secret or environment-variable mechanism for the
`X-API-Key` header. Do not run a shell command with
`--header "X-API-Key: $SIMPLEFORMS_MCP_API_KEY"`: the shell expands the key into
the command-line arguments, where other processes may observe it. If the client
has no safe way to supply a custom header, explain that limitation instead of
asking the user to paste the key into chat or a command.

### Codex (OpenAI)

In `~/.codex/config.toml` (user-level, not project-level):

```toml
[mcp_servers.sf]
url = "https://api.simpleforms.ru/mcp"
env_http_headers = { "X-API-Key" = "SIMPLEFORMS_MCP_API_KEY" }
enabled = true
```

`SIMPLEFORMS_MCP_API_KEY` must be in the environment of the Codex process at
launch. Fully restart the client after configuring.

### Clients with JSON config and HTTP + headers support

Cursor, Cherry Studio, Qwen Code, Kimi CLI, Trae, Cline, Roo Code and similar —
general shape (check field names in the client's docs, e.g. `url` / `httpUrl` /
`serverUrl`, `type: "streamableHttp"`):

```json
{
  "mcpServers": {
    "sf": {
      "url": "https://api.simpleforms.ru/mcp",
      "headers": { "X-API-Key": "${SIMPLEFORMS_MCP_API_KEY}" }
    }
  }
}
```

If the client cannot substitute environment variables in headers, the key goes
into a protected settings field of the client, not into a project file.

### stdio-only clients (mcp-remote bridge)

Requires Node.js. The client must pass the key variable to the process via its
secret environment:

```json
{
  "mcpServers": {
    "sf": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.simpleforms.ru/mcp",
        "--transport", "http-only",
        "--header", "X-API-Key:${SIMPLEFORMS_MCP_API_KEY}"
      ],
      "env": { "SIMPLEFORMS_MCP_API_KEY": "<enter in a protected field / from secret store>" }
    }
  }
}
```

On Windows `npx.cmd` may be required.

### Agent platforms (Yandex AI Studio, GigaChain / LangChain, etc.)

- **Yandex AI Studio:** MCP Hub → connect an external MCP server, set the URL and
  the `X-API-Key` header, then add the server to the agent as an MCP tool.
- **GigaChat via GigaChain / LangChain MCP adapters:** an HTTP MCP client with
  `url="https://api.simpleforms.ru/mcp"`, `transport="streamable_http"` and
  `headers={"X-API-Key": os.environ["SIMPLEFORMS_MCP_API_KEY"]}`.

## Step 4. Verify the connection

After restarting the client:

1. Make sure `templates_*` tools appear in the tool list.
2. Call `templates_list` with `purpose="read"`, `limit=3` and show the user the
   template names.
3. Optionally call `templates_get_capabilities` to learn server versions and limits.

Do not create or modify anything at this step.

## Troubleshooting

| Symptom | What to check |
|---|---|
| HTTP 401 | Key missing, revoked or wrong; the header must be sent exactly once |
| HTTP 403 | A corporate REST key was used instead of the personal MCP key |
| HTML or redirect instead of an MCP response | The cabinet URL was used instead of `https://api.simpleforms.ru/mcp` |
| Tools did not appear | Client not restarted, or it does not support HTTP headers |
| `templates_not_found` | The user has no access to that template |
| Reading works, changes are rejected | The template is running (InProgress) — edits go to a draft of a new version |

## What next

Once connected, tell the user what they can ask for, for example:

- «Покажи структуру анкеты X и найди ошибки в логике переходов» (show the structure of survey X and find logic errors)
- «Собери новую анкету по этому брифу» (build a new survey from this brief)
- «Добавь английскую версию анкеты» (add an English version of the survey)

Before creating or editing a template, fetch the server prompt
`templates_edit_safely` via `prompts/get` and give the assistant the
[questionnaire methodology](ai-client-templates/questionnaire-methodology.md).
Connecting to MCP does not load those instructions automatically. Check
`templates_get_capabilities` and prefer declarative `schemaVersion=2.2`: a new
root question must explicitly set `stage` to `screener` or `main`; questions
inside a section or cycle inherit its stage. Do not put ordinary interview
questions in the screener merely because an older schema defaults to it.

Preview every proposed change, show the result to the user, and apply it only
after their confirmation.