---
name: viktor-agent-setup
description: "Viktor is an AI employee that works in Slack and Microsoft Teams. Use this to connect Claude Code, Cursor or any MCP client to Viktor's remote MCP server with a scoped API key, prove the connection with a read-only call, then hand him real work."
metadata:
  author: Viktor
  url: https://viktor.com/skill.md
  last-reviewed: 2026-10-17
---

# Connect an MCP client to Viktor

Viktor does the work a teammate would: reports, research, spreadsheets, CRM updates, code, dashboards. Through his MCP server, another tool can delegate a task to him and get the finished result back, using the integrations the Viktor workspace has already connected.

## Before you start

- A Viktor workspace. Sign up free at https://app.viktor.com/signup with Slack or Microsoft Teams.
- API keys need a paid plan or Enterprise. Upgrade at https://app.viktor.com/settings/subscription/plans if the workspace is on the free plan.
- An MCP client that supports remote servers over Streamable HTTP (Claude Code, Cursor and most current clients do).

## 1. Pick the interface

- **MCP** (recommended for coding tools): https://api.viktor.com/mcp, Streamable HTTP. Docs: https://viktor.com/docs/mcp-server
- **REST API** for scripts and back ends: https://api.viktor.com/api/public/v1. Docs: https://viktor.com/docs/public-api
- **OpenAI- or Anthropic-compatible API** if your code already uses those SDKs: https://api.viktor.com/api/compat/v1 (OpenAI style) or https://api.viktor.com/api/compat (Anthropic style), model `viktor`. Docs: https://viktor.com/docs/chat-completions

The rest of this guide covers MCP.

## 2. Create a scoped API key

Open https://app.viktor.com/settings/api-keys and create a personal or team key. Grant the least it needs:

- No scope at all to run `whoami` and prove the connection.
- `threads:create`, `runs:create` and `runs:read` once you want Viktor to take a task with `ask_viktor`.
- Add other scopes only for the tools you will call. The server lists only the tools the key's scopes allow.

Keep the key in your client's secret store or an environment variable. Never paste a live key into a shared or committed config file.

## 3. Add the server

Name the server `viktor`. Send the key as `Authorization: Bearer <VIKTOR_API_KEY>` or `x-api-key: <VIKTOR_API_KEY>`.

Claude Code:

```bash
claude mcp add --transport http viktor https://api.viktor.com/mcp \
  --header "Authorization: Bearer $VIKTOR_API_KEY"
```

Cursor (`~/.cursor/mcp.json` or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "viktor": {
      "url": "https://api.viktor.com/mcp",
      "headers": { "Authorization": "Bearer <VIKTOR_API_KEY>" }
    }
  }
}
```

Other clients: enter the same URL and header, and choose Streamable HTTP, not the legacy SSE transport.

## 4. Prove it with a read

Call `whoami`. It needs no scope and returns the key type (personal or team), the granted scopes and the rate limits. Report those back to the person who asked for the setup before doing anything else.

## 5. Keep setup and work separate

Setup ends at `whoami`. Do not call `ask_viktor`, `create_thread` or `run_script` as part of setup: they start real work and use the workspace's credits. Start work only when someone asks for a task.

## 6. Hand Viktor a task

Call `ask_viktor` with a plain-language `message`, an optional `timeout_seconds` and an `idempotency_key`. It starts the task and waits for the result. Results can include Markdown, structured JSON and files; fetch files with `get_file_download_url`.

## When something goes wrong

- **401 or 403:** the key is missing, revoked or sent in the wrong header.
- **No tools listed:** run `whoami`, then add the scopes the tools need and refresh the client's tool list.
- **`missing_scope`:** add the named scope to the key, or use a different tool.
- **`wait_timed_out: true`:** the task is still running. Call `wait_for_run` with the returned `run_id`. Do not call `ask_viktor` again, or you may start the same work twice.
- **Run status `requires_action`:** Viktor finished by asking for input, a decision or an approval. Read the result and answer with `send_message` on the same thread.
- **`thread_busy`:** wait for the active run before sending another message to that thread.
- **`rate_limit_exceeded`:** wait for the retry interval, then call again.

## More

- MCP server reference: https://viktor.com/docs/mcp-server
- Public API reference: https://viktor.com/docs/public-api
- Pricing and credits: https://viktor.com/pricing
- Security: https://viktor.com/security
- Integration catalogue (JSON): https://viktor.com/integrations.json
- What Viktor is: https://viktor.com/llms.txt

Last reviewed: 2026-10-17.