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>orx-api-key: <VIKTOR_API_KEY>(API keys require a paid plan or Enterprise).
- Session model: Stateless Streamable HTTP with lazy authentication (
initializeandtools/listwork before sign-in;tools/callrequires authentication).
Connect with OAuth (Claude & ChatGPT)
Claude.ai, Claude Desktop, Claude Mobile, and Claude Cowork
- Open Settings → Connectors (or browse the Claude Directory) and select Viktor (or click Add custom connector and enter
https://api.viktor.com/mcp). - 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.
- 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:createruns:createruns: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:
- Call
create_threadto queue work without waiting. - Call
wait_for_runorget_runwith the returned run ID. - Call
send_messageon the same thread to continue the conversation with its history. - Use
get_file_download_urlfor any artifact IDs returned in the result.
Tool reference
| Tool | Title | What it does | Required scopes |
|---|---|---|---|
ask_viktor | Ask Viktor | Start a new thread and wait for its result | threads:create, runs:create, runs:read |
create_thread | Create Thread | Start a new thread and queue a run without waiting | threads:create, runs:create |
send_message | Send Message | Continue an existing thread and queue a run | messages:create, runs:create |
wait_for_run | Wait for Run | Wait for a run to finish and return its result | runs:read |
get_run | Get Run Status | Read a run's current status | runs:read |
get_run_result | Get Run Result | Fetch a terminal run's result | runs:read |
cancel_run | Cancel Run | Request cancellation of an in-flight run | runs:create |
list_threads | List Threads | List the key's threads, newest first | threads:read |
get_thread | Get Thread Status | Get a thread's status | threads:read |
list_messages | List Thread Messages | List user-visible messages in a thread | messages:read |
list_runs | List Thread Runs | List a thread's runs, newest first | runs:read |
run_script | Run Python Script | Run a Python script directly in the sandbox and wait for its result (API key only) | scripts:execute |
wait_for_script_run | Wait for Script Run | Wait for a script run to finish and return its result (API key only) | scripts:execute |
get_script_run | Get Script Run Status | Read a script run's status and result (API key only) | scripts:execute |
cancel_script_run | Cancel Script Run | Cancel a queued script run (API key only) | scripts:execute |
list_integrations | List Connected Integrations | List connected integrations and their SDK modules (API key only) | integrations:read |
list_integration_tools | List Integration Tools | List an integration's SDK tools with schemas and snippets (API key only) | integrations:read |
get_file_download_url | Get File Download URL | Exchange an artifact token for a short-lived URL | files:read |
list_audit_events | List Workspace Audit Events | Pull workspace audit events, cursor-paginated (team keys on Enterprise workspaces only) | audit:read |
whoami | Identify API Key | Identify 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: callwait_for_runagain 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 callget_runinstead of waiting.
Support
For questions, account help, or data deletion requests, contact support@viktor.com or see our Privacy Policy.