Viktor

Delegue tarefas para Viktor, um funcionário de IA com mais de 3.200 integrações, e obtenha os resultados.

Servidor MCP hospedado

npx add-mcp 'https://api.viktor.com/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

The Viktor MCP server lets Claude, ChatGPT, and any MCP-compatible agent delegate work to Viktor. It exposes the same threads, runs, results, and files as the Viktor Public API, with agent-friendly tools that can start a task and wait for its result in one call.

  • Server URL: https://api.viktor.com/mcp
  • Transport: Streamable HTTP (2025-03-26)
  • Authentication:
    • OAuth 2.1 + PKCE: Sign in with your Viktor account and pick a workspace (supported on all Viktor plans for Claude.ai, Claude Desktop, Claude Mobile, Claude Cowork, Claude Code, and ChatGPT).
    • Viktor API key: Pass Authorization: Bearer <VIKTOR_API_KEY> or x-api-key: <VIKTOR_API_KEY> (API keys require a paid plan or Enterprise).
  • Session model: Stateless Streamable HTTP with lazy authentication (initialize and tools/list work before sign-in; tools/call requires authentication).

Connect with OAuth (Claude & ChatGPT)

Claude.ai, Claude Desktop, Claude Mobile, and Claude Cowork

  1. Open Settings → Connectors (or browse the Claude Directory) and select Viktor (or click Add custom connector and enter https://api.viktor.com/mcp).
  2. Click Connect. You are redirected to Viktor to sign in with your work email or Google account and choose the Viktor workspace Claude should work in.
  3. Review the permissions on the consent screen and click Allow.

Claude Code

Add Viktor as a remote HTTP MCP server (or install the Viktor plugin):

claude mcp add --transport http viktor https://api.viktor.com/mcp

Then run /mcp inside Claude Code to complete browser OAuth sign-in, or pass a scoped API key header as shown below.

ChatGPT

In ChatGPT, open Settings → Connectors, choose Viktor, and complete the Viktor sign-in and workspace selection flow.

Managing or disconnecting an OAuth connection

OAuth sign-in creates a personal connector key named Claude or ChatGPT in your Viktor account, scoped to task, thread, message, run, and file operations (run_script, list_integrations, list_integration_tools, list_audit_events, and whoami are never exposed over OAuth).

You can disconnect at any time at app.viktor.com/connect/chatgpt/manage (or app.viktor.com/connect/chatgpt/manage?client=claude for Claude), by revoking the key in Settings → API Keys, or from your AI client's connector settings.

Connect with a Viktor API key

1. Create a scoped API key

API keys are available on paid plans and Enterprise. If your workspace is on the free plan, upgrade first or connect via OAuth above.

Open Settings → API Keys and generate a personal or team key. For the simplest ask_viktor workflow, grant:

  • threads:create
  • runs:create
  • runs:read

Add other scopes only when the MCP client needs the corresponding tools. The server advertises only tools allowed by the key's current scopes.

2. Add the remote server to your MCP client

Every API-key client needs the server URL and an authentication header. Either header style works:

  • Authorization: Bearer <VIKTOR_API_KEY>
  • x-api-key: <VIKTOR_API_KEY>

Claude Code (API key)

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

Cursor

Add the server to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

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

Other clients

Most MCP clients accept the same mcpServers JSON shape as the Cursor example, or offer a settings screen where you enter the URL and header. If your client asks for a transport, choose Streamable HTTP, not the legacy SSE transport.

Use your client's secret or environment-variable support instead of saving a live key directly in a shared configuration file.

3. Verify an API-key connection

Call whoami. It requires no scope and returns the key type, granted scopes, the workspace's rate-limit tier, and the active (tier-scaled) rate limits. If other tools are missing, update the key's scopes in the Viktor dashboard and refresh the client's tool list.

Example prompts & recommended workflow

Once connected, you can ask Claude or ChatGPT to delegate tasks directly to Viktor:

  • "Ask Viktor to summarize our top customer support blockers from this week and list the open threads." (ask_viktor)
  • "Ask Viktor to generate a CSV of this month's closed deals and give me the download link." (ask_viktor → get_file_download_url)
  • "List my recent Viktor threads and check the status of the latest run." (list_threads → list_runs / get_run)
  • "Follow up on that Viktor thread and ask Viktor to break the numbers down by region." (send_message → wait_for_run)

For a one-off task, call ask_viktor with a message:

{
  "message": "Analyze this month's revenue and summarize the biggest changes.",
  "speed": "smarter",
  "timeout_seconds": 120,
  "idempotency_key": "monthly-revenue-2026-07"
}

ask_viktor creates a thread, starts a run, waits up to timeout_seconds, and returns the result when it is ready. Results can contain Markdown, structured JSON, and file artifacts.

If the wait ends first, the response includes wait_timed_out: true and the run_id. Call wait_for_run with that ID. Do not call ask_viktor again, because that can start duplicate work unless the same idempotency key is reused.

For long-running or interactive workflows:

  1. Call create_thread to queue work without waiting.
  2. Call wait_for_run or get_run with the returned run ID.
  3. Call send_message on the same thread to continue the conversation with its history.
  4. Use get_file_download_url for any artifact IDs returned in the result.

Tool reference

ToolTitleWhat it doesRequired scopes
ask_viktorAsk ViktorStart a new thread and wait for its resultthreads:create, runs:create, runs:read
create_threadCreate ThreadStart a new thread and queue a run without waitingthreads:create, runs:create
send_messageSend MessageContinue an existing thread and queue a runmessages:create, runs:create
wait_for_runWait for RunWait for a run to finish and return its resultruns:read
get_runGet Run StatusRead a run's current statusruns:read
get_run_resultGet Run ResultFetch a terminal run's resultruns:read
cancel_runCancel RunRequest cancellation of an in-flight runruns:create
list_threadsList ThreadsList the key's threads, newest firstthreads:read
get_threadGet Thread StatusGet a thread's statusthreads:read
list_messagesList Thread MessagesList user-visible messages in a threadmessages:read
list_runsList Thread RunsList a thread's runs, newest firstruns:read
run_scriptRun Python ScriptRun a Python script directly in the sandbox and wait for its result (API key only)scripts:execute
wait_for_script_runWait for Script RunWait for a script run to finish and return its result (API key only)scripts:execute
get_script_runGet Script Run StatusRead a script run's status and result (API key only)scripts:execute
cancel_script_runCancel Script RunCancel a queued script run (API key only)scripts:execute
list_integrationsList Connected IntegrationsList connected integrations and their SDK modules (API key only)integrations:read
list_integration_toolsList Integration ToolsList an integration's SDK tools with schemas and snippets (API key only)integrations:read
get_file_download_urlGet File Download URLExchange an artifact token for a short-lived URLfiles:read
list_audit_eventsList Workspace Audit EventsPull workspace audit events, cursor-paginated (team keys on Enterprise workspaces only)audit:read
whoamiIdentify API KeyIdentify the key, scopes, and rate limits (API key only)None

Script runs without an agent

run_script executes one Python script directly in the workspace sandbox — no agent turn. The script runs as the key owner's identity and can call connected integrations through the workspace SDK. Discover what it can call with list_integrations and list_integration_tools; each tool comes with a runnable snippet that run_script accepts as-is. Output files written to the directory in the VIKTOR_OUTPUT_DIR environment variable come back as artifacts for get_file_download_url. If the wait ends before the script finishes, the response includes wait_timed_out: true — continue with wait_for_script_run, not another run_script. See script runs in the Public API guide for limits.

Structured output

ask_viktor, create_thread, and send_message accept the same response_format JSON Schema as the REST API. When supplied, the completed result includes a validated json value. See the Public API guide.

Timeouts, progress, and retries

ask_viktor and wait_for_run perform bounded server-side polling. Clients that send an MCP progress token receive best-effort progress notifications while waiting. A wait costs only the tool call's own rate-limit unit, however long it polls; each key can hold 8 waits open at once, and a ninth returns wait_limit_exceeded.

Every tool call is rate limited against the same policy as its REST equivalent, scaled to the workspace's plan tier (higher plans get proportionally higher limits — see the Public API guide). If a wait times out, call wait_for_run again with the same run ID. Use idempotency_key whenever a tool starts a run so reconnects and retries cannot duplicate work.

Errors and troubleshooting

Authentication failures are plain HTTP 401 or 403 responses (and OAuth token/refresh errors return RFC 6749 invalid_grant) so MCP clients can recognize credential problems and prompt for re-authentication automatically. Tool failures are machine-readable JSON strings with an error and message, and may include http_status, scope, or rate-limit details.

Common fixes:

  • OAuth prompt reappears: your refresh token expired or the connector key was revoked; complete the Viktor sign-in flow again.
  • No tools appear (API key): verify the key with whoami, then grant the required scopes.
  • missing_scope: add the named scope to the key or choose a different tool.
  • wait_timed_out: call wait_for_run again with the returned run ID.
  • thread_busy: wait for the active run before sending another message to that thread.
  • rate_limit_exceeded: wait for the retry interval before calling again.
  • wait_limit_exceeded: the key already has 8 waits open; let one finish, or call get_run instead of waiting.

Support

For questions, account help, or data deletion requests, contact support@viktor.com or see our Privacy Policy.