StefanBrain

Der Remote-MCP-Server von StefanBrain. Bitte StefanBrain, die Direct-Response-KI-Plattform für DTC-Marken und Paid-Ads-Teams, um Meta-Ad-Hooks, Anzeigentexte, Videoskripte, Angles und Recherchen aus Claude, ChatGPT, Cursor oder Windsurf.

Gehosteter MCP-Server

npx add-mcp 'https://stefanbrain.com/api/developers/v1/mcp'

Installiert in Claude Code, Codex, Cursor und mehr

Dokumentation

Agent Instructions

Follow the content contract in AGENTS.md. Treat text as the canonical explanation; video and screenshots enhance it. Do not publish unverified product behavior or duplicate an existing canonical article.

StefanBrain MCP

Connect the StefanBrain product MCP to Codex, Claude, ChatGPT, Cursor, Windsurf, or another MCP client.

StefanBrain exposes a remote MCP server over streamable HTTP:

https://stefanbrain.com/api/developers/v1/mcp

[!NOTE]

This page documents the StefanBrain product MCP, which can run StefanBrain tools and complete work. It is separate from the read-only documentation MCP at https://docs.stefanbrain.com/mcp.

Use OAuth for connector interfaces (claude.ai, Claude Desktop, ChatGPT) and for coding assistants that support MCP OAuth, such as Claude Code. Use an API key for clients that send a fixed header (Cursor, Windsurf, Codex) and for SDKs and scripts. For standard member accounts, both bill the plan pool on MCP.

If StefanBrain is already connected in a client, keep that connection. Adding it again under another name loads every tool twice.

Stay on v1

Use this pinned address to keep the v1 tool catalog:

https://stefanbrain.com/api/developers/v1/mcp/legacy

It accepts the same API keys and OAuth sign-in as the existing address. Existing v1 OAuth tokens work on both addresses without new consent.

Clients that can set headers can also pin the existing address with StefanBrain-Version: 2026-10-20. The pinned address returns Deprecation and Link headers. There is no shutdown date.

Use ask_stefanbrain

ask_stefanbrain is the main MCP tool. In your assistant, say use StefanBrain or use SB, then describe the work. Your assistant calls the tool; StefanBrain completes the turn on its servers and returns the response.

You can use it to:

  • Request ad angles, copy, reviews, strategy, research, or another complete work product.
  • Send up to 10 image URLs through image_urls for JPEG, PNG, WebP, or GIF inputs.
  • Upload local images, PDFs, documents, and spreadsheets through POST /api/developers/v1/files, then pass the returned upload_... identifiers in file_ids. The upload needs an unscoped key or a key with the runs scope. A key scoped only to mcp gets 403 api_key_scope_forbidden; call stage_file instead.
  • Call stage_file when the MCP client cannot send raw HTTP. Stage a public URL or base64-encoded bytes, then pass its upload_id in file_ids.
  • Include a video or web-page URL in message; StefanBrain detects it without a separate URL field.

Follow-up asks continue the same StefanBrain chat. To start a fresh one, the assistant passes chat: "new".

Uploads for file_ids expire after 24 hours. One ask accepts at most 10 attachments across image_urls and file_ids, and its message can be up to 32,000 characters. Each image URL must be a public JPEG, PNG, WebP, or GIF of 15 MB or less.

Inside an ask or an Agent Run, StefanBrain never sends email or changes schedules, whichever lane pays for the turn. prepare_launch only stages a draft. Open the reply's app_url to finish those in the app. Calling send_email directly sends immediately.

Leave ask_stefanbrain.brain unset. It is for StefanBrain admins. For any other account, the call fails with an error that tells you to omit it.

Use a direct tool when you need its raw result. Use ask_stefanbrain when StefanBrain should plan and complete the work. ask_stefanbrain has no JSON-schema option; it returns free text in answer. For schema-constrained JSON, start an Agent Run with output_config.format.

Write a good ask

StefanBrain is the expert, so your assistant should pass the request on rather than write its brief. The ask_stefanbrain message field and the server instructions tell assistants this. Add it to your own agent's instructions if it still over-specifies:

  • Send the request in the user's own words.
  • Add the facts StefanBrain can't see: the product, offer, audience, links, files, where the copy will run and its character limits, and any requirement the user stated.
  • Leave out writing instructions the user didn't give, such as a framework, structure, word count, tone, angles, or sample copy. StefanBrain applies its own copywriting method, and extra instructions override it.
  • To revise, send the feedback as a short follow-up in the same chat instead of the whole brief again.

Read the answer

ask_stefanbrain waits up to about 55 seconds for the turn. A turn that finishes in that window returns its answer inline. Otherwise the call returns a parked result with family: "mcp_ask", a run_… run_id, and status queued or running. Poll get_job_status with that family and run_id about every 10 seconds, then call get_job_result when status is succeeded, failed, or cancelled.

While the turn runs, get_job_status returns progress: the model calls and tool calls the turn has started, and last_activity_at, the time of its newest event. phase puts the same facts in one line, for example Working · 285 model calls, 388 tool calls · last activity 4s ago · 60m 10s in. The turn is working while last_activity_at keeps moving. A long rewrite can take an hour. Keep polling: asking again starts a second turn, and both are billed.

Set the client's tool timeout above 60 seconds. Clients that send an MCP progressToken get progress notifications while the ask waits. Use cancel_job to stop a queued or running mcp_ask job.

An ask returns answer, chat, and app_url, plus steps and produced_documents when the turn has them. A parked ask's get_job_result returns the same fields, with status and last_error. produced_documents holds the text files the turn wrote, up to 16,000 characters each and 48,000 in total. answer repeats the steps and files for clients that read only text.

message accepts up to 32,000 characters. For longer briefs or research, use stage_file, pass its returned upload_id in file_ids, and keep message short.

Handle a busy chat

When you omit chat, asks reuse the session's chat. If that chat is busy, StefanBrain runs the new ask independently in a fresh chat on both API versions. The result includes the new chat and session_chat_busy, which names the busy original chat. This fresh chat has project context but none of the original chat's conversation history.

A session label still points to its original chat. Later asks with that label try the original chat again; to continue a split ask, pass its returned chat explicitly. Keyed retries with the same arguments recover the same run and fresh chat, including after a lost response.

Explicit busy chats depend on your StefanBrain-Version:

  • 2026-11-01: the input steers the active turn, like the web composer. steered_into_run_id names the run it joined. The returned run_id is this input's handle on the shared turn and result. It does not start or bill a separate turn. Additional model work still counts toward that turn's usage.
  • 2026-10-20: the call returns a typed busy conflict with refusal.kind: "busy", naming the blocking run when known. Wait, then retry the same request and key.

For 2026-11-01, pass on_busy: "reject" to refuse an explicit busy chat instead of steering it. REST /tools/ask_stefanbrain follows the same rules. Independent work belongs in a separate chat. Your account must be enabled for 2026-11-01 to use that contract.

An overlapping retry with the same idempotency_key also returns the typed busy conflict while the original call holds that key. Wait, then retry identical arguments with the same key to recover the original run and chat. A retry_after_ms is included when the server supplies a retry interval. Only on_busy: "reject" is supported as an explicit option. A refused ask does not use up an idempotency_key, so retry the same request with the same key. Use a new key for changed input.

If StefanBrain is briefly at capacity when an ask starts, the call returns a retryable error (upstream_unavailable in the tool result on MCP, 429 runtime_capacity_busy with Retry-After on REST). Retry after a few seconds.

Use different session labels for independent workstreams that need their own continuing conversation.

Retry an ask safely

Pass idempotency_key before retrying an ask whose response may have been lost. A repeated key returns the original turn and run_id without another charge. A key reused with a different message or attachments returns a conflict error (idempotency_mismatch) instead: send that ask with a new key. Asks with image_urls fetch the images again on every call, so retry those with a new key.

On both API versions, ask keys are scoped to your account and retained for 24 hours after acceptance, including across UTC midnight. Retries keep returning the original run while that window lasts or the run remains active. Once the window ends and the run finishes, reusing the key can start another billed run. Use a new key for new work. Keep the same project, session, explicit chat, and arguments on every retry. REST /tools/ask_stefanbrain uses the same key space.

Billing and transport behavior

For standard member accounts, MCP calls use the plan's monthly pool instead of the API wallet. This applies to OAuth tokens and API keys used on MCP.

Contracted partner accounts can have API-key MCP traffic billed to the API wallet. OAuth still uses the subscription allowance. Confirm partner terms with your StefanBrain contact.

  • Use MCP for interactive work inside an assistant.
  • Use the REST API for integrations, pipelines, and automated or machine-scale traffic.

The MCP server is stateless and does not issue an Mcp-Session-Id. Each client message is one authenticated POST, so reconnecting is safe. A standalone GET request returns 405 by design; the server does not send server-initiated messages.

Choose a client

Verified means the stated setup or behavior ran at the boundary named below. Unverified means the full connection has not been exercised here. Every line in a code block inherits the label directly above it.

ClientSetup statusLong calls and Tasks
claude.ai / Claude Desktop remote connectorUnverified end to end; OAuth setup is documented.Claude documents a 240-second call limit. Progress renewal and native Tasks are unverified in these hosts.
CursorUnverified end to end; configuration is documented.The default deadline and native Task following are unverified.
Claude Code 2.1.312Verified local HTTP/stdio behavior; StefanBrain OAuth sign-in is unverified.Foreground and ordinary background results work.
Codex CLI 0.165.0Verified native read-only call on staging; production connection is unverified.Default 65-second completion and a configured deadline are verified locally. Native Task following is unsupported on the tested path.
ChatGPT custom app / developer modeUnverified end to end; OAuth setup is documented.Its numeric deadline and native Task following are unverified. MCP Events requires a separate integration.
VS Code + GitHub CopilotUnverified end to end; released source implements MCP Tasks dated 2025-11-25.Completion is unverified.
Gemini CLI 0.65.0Verified local stdio call; StefanBrain HTTP connection is unverified.The documented default is 600,000 milliseconds. A default 580-second stdio call completed; a 610-second call timed out after 600 seconds. StefanBrain HTTP is unverified. Native Task following is unsupported on the tested path.
WindsurfUnverified end to end; configuration is documented.Deadline, progress renewal and native Task following are unverified.
Plain HTTP scriptVerified local held JSON; StefanBrain JSON-only transport is unverified.Your script supplies its timeout, response parser and continuation. Use REST for automated integrations.

These host results do not change v1's parked-job flow. Progress indicates activity; it does not replace the completed answer.

Connect Codex

Unverified secret-loading example: supply your API key through your secret manager or current shell. This placeholder never belongs in a committed file.

export STEFANBRAIN_API_KEY="stefan_sk_your_key_here"

Verified staging configuration; unverified production URL: add this temporary connection check to ~/.codex/config.toml. Every configuration line except the production URL was exercised with a staging test credential.

[mcp_servers.StefanBrain]
url = "https://stefanbrain.com/api/developers/v1/mcp"
bearer_token_env_var = "STEFANBRAIN_API_KEY"
tool_timeout_sec = 300
enabled_tools = ["account_status"]

[mcp_servers.StefanBrain.tools.account_status]
approval_mode = "approve"

This check exposes and preapproves only the read-only account_status tool. After it passes, remove enabled_tools to expose the full catalog. Other tools retain your normal approval policy. The key stays in your environment. Codex's public configuration reference lists a 60-second default; the tested 0.165.0 release source sets 300 seconds. A local 65-second call completed. Set the value explicitly when your workflow depends on it. A 300-second setting is not a guarantee of completion for longer work.

Verified native staging call with Codex 0.165.0; production call unverified: this check reports the plan and remaining allowance without starting generation work.

codex --no-daemon -a never exec --sandbox read-only --skip-git-repo-check --json \
  'Discover StefanBrain account_status, call it once with lane="all", and report my plan and remaining allowance. Do not start paid work.'

Keep tool discovery enabled. Without discovery, a deferred tool may appear unavailable. Without the scoped approval above, -a never can refuse the call with “MCP tool call requires approval.”

If Codex exposes MCP through an execution cell, resume a yielded cell with the host's wait control until it finishes. Returning a final answer while that cell is pending can end observation. This is separate from calling a StefanBrain status tool.

There is no verified Codex switch that follows native MCP Tasks. For v1, use the returned family and run_id with the job tools.

Connect Claude Code

Unverified OAuth connection; command syntax verified with 2.1.312: add the server, then sign in with your own StefanBrain account.

claude mcp add --transport http --scope user stefanbrain \
  https://stefanbrain.com/api/developers/v1/mcp
claude mcp login stefanbrain

Remove --scope user for a project-only connection. Keep the name stefanbrain: sb init writes its project entry under that name.

Unverified StefanBrain API-key connection; documented environment interpolation: the single quotes preserve the variable reference in Claude's configuration.

claude mcp add --transport http --scope user stefanbrain \
  https://stefanbrain.com/api/developers/v1/mcp \
  --header 'Authorization: Bearer ${STEFANBRAIN_API_KEY}'

Do not use shell-expanded credentials in a committed configuration.

Choose foreground completion

Verified locally: CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0 disables ordinary automatic backgrounding. Unverified long-duration configuration: the following also requests a longer total budget. MCP_TOOL_TIMEOUT is in milliseconds; progress does not extend this total budget.

MCP_TOOL_TIMEOUT=1800000 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0 claude

The 1,800,000-millisecond value requests a 30-minute budget; a 30-minute completion has not been verified. Remote calls also have an idle deadline. Progress can keep the idle check alive.

Ordinary auto-backgrounding is a different mode: the documented threshold is 120 seconds. A 130-second streaming call completed with CLAUDE_AUTO_BACKGROUND_TASKS=1, without a server Task handle. Its work does not gain remote Task durability.

Connect Cursor

Unverified end to end: add this to .cursor/mcp.json for one project or ~/.cursor/mcp.json globally. Start Cursor with the named environment variable available.

{
  "mcpServers": {
    "StefanBrain": {
      "url": "https://stefanbrain.com/api/developers/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:STEFANBRAIN_API_KEY}"
      }
    }
  }
}

Enable the server and its tools in Cursor's MCP settings. Its real default tool deadline is unverified. Do not choose a long wait from an assumed Cursor timeout. No native Task-following setting is verified.

Connect Windsurf

Unverified end to end: add this to ~/.codeium/windsurf/mcp_config.json. Windsurf uses serverUrl.

{
  "mcpServers": {
    "StefanBrain": {
      "serverUrl": "https://stefanbrain.com/api/developers/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:STEFANBRAIN_API_KEY}"
      }
    }
  }
}

Its deadline and native Task following remain unverified.

Connect an OAuth client

Unverified end to end for each hosted client: use this product endpoint with your own StefanBrain login:

https://stefanbrain.com/api/developers/v1/mcp
ClientDocumented setup stepsVerification
claude.ai / Claude Desktop remote connectorOpen Customize > Connectors, add a custom connector named StefanBrain, and paste the URL. Managed organizations may require an administrator to add it.Unverified GUI sign-in, timeout, progress and Tasks. The documented tool limit is 240 seconds.
ChatGPTEnable the custom-app/developer setting available to your workspace. Add a custom MCP server named StefanBrain, paste the URL, and choose OAuth. Labels vary by workspace.Unverified GUI sign-in, deadline and native Tasks.
Other OAuth clientsAdd the remote URL, sign in to StefanBrain and select Allow access.Unverified host-specific behavior.

Add StefanBrain to Claude opens its connector dialog with the name and URL filled in. That shortcut is unverified end to end.

Connecting requires an active StefanBrain plan or trial. Without one, the approval page shows Developer access required, and API-key calls return 403 developer_access_forbidden.

You do not need an API key or Client ID for the OAuth flow. Disconnect in the client to revoke access. Access tokens last one hour; rotating refresh tokens expire 60 days after issue. StefanBrain has no in-app list of connected OAuth clients.

If registration fails for an older connection, remove it and add it again. Task support in Claude Code does not establish support in hosted Claude or Desktop chat.

Connect VS Code and GitHub Copilot

Unverified end to end; documented VS Code configuration: place this in .vscode/mcp.json. The password input keeps a literal key out of the file.

{
  "inputs": [
    {"type": "promptString", "id": "stefanbrain-key", "description": "StefanBrain API key", "password": true}
  ],
  "servers": {
    "StefanBrain": {
      "type": "http",
      "url": "https://stefanbrain.com/api/developers/v1/mcp",
      "headers": {"Authorization": "Bearer ${input:stefanbrain-key}"}
    }
  }
}

Trust the server, use Copilot Agent mode and enable its tools. Stable VS Code 1.143.1 source follows 2025-11-25 Tasks automatically when the server advertises the matching capability and tool hint. A live completion is unverified.

Connect Gemini CLI

Unverified StefanBrain HTTP connection; documented configuration: merge this into ~/.gemini/settings.json. timeout is in milliseconds.

{
  "mcpServers": {
    "StefanBrain": {
      "httpUrl": "https://stefanbrain.com/api/developers/v1/mcp",
      "headers": {"Authorization": "Bearer ${STEFANBRAIN_API_KEY}"},
      "timeout": 600000
    }
  }
}

Verified locally: Gemini CLI 0.65.0 used the CSV from a default 580-second stdio call. A 610-second call returned a timeout after 600 seconds. Unverified: StefanBrain HTTP authentication and native Task following. Long calls remain subject to the configured deadline; a progress notification is not a completed result.

Connect another streamable-HTTP client

Unverified generic setup: adapt this documented shape to the client's own configuration and secret interpolation. The token below is a placeholder.

{
  "type": "http",
  "url": "https://stefanbrain.com/api/developers/v1/mcp",
  "headers": {"Authorization": "Bearer stefan_sk_your_key_here"}
}

Header clients can also send x-api-key: stefan_sk_....

Unverified bridge: for a stdio-only client, the documented bridge command is:

npx -y mcp-remote https://stefanbrain.com/api/developers/v1/mcp \
  --header "Authorization: Bearer ${STEFANBRAIN_API_KEY}"

Unverified product call; verified local held JSON only: a plain HTTP script must send the authenticated POST, wait for its response and parse the actual content type. StefanBrain can return SSE-framed JSON. A script that expects only one JSON document must not treat that stream as a parsed result. Scripts do not gain native Tasks, progress-driven continuation or artifact downloads automatically. Use the REST API for pipelines and machine-scale traffic.

Available tool areas

The MCP surface serves the supported developer-tool catalog. tools/list is authoritative for the tools available to the authenticated user in the current deployment.

Tool availability can depend on account permissions, connector access, and deployment configuration. Do not treat this summary as an exhaustive static list.

  • Ask StefanBrain: ask_stefanbrain
  • Chats, projects, and products: search_chats, read_chat, list_chats, query_projects, get_project_context, edit_project, and manage_products
  • Research: web_search, web_extract, agentcore_browser, website_traffic, amazon_search, amazon_product, google_trends, reddit_search, reddit_thread, and scrape_social_comments
  • Meta: get_meta_ad reads one public Ad Library ad as an asynchronous job. meta_ad_accounts_search and meta_ads_insights are served directly and need a connected Meta account.
  • Connected accounts: Connector tools are not served directly over MCP. Ask for connector work with ask_stefanbrain, which runs a full StefanBrain turn with your connected accounts.
  • Copy, creative, and research jobs (asynchronous): review_copy, find_angles, create_images, edit_image, review_funnel, and research_shortform
  • Jobs: get_job_status, get_job_result, and cancel_job
  • Files: stage_file for a public URL or base64 payload that should become an upload_... id
  • Launch: find_creative lists the images and videos you can launch, from your Launch library and your /videos renders. upload_creative adds one image or video (a public URL, a staged upload_... id, or a file path in the chat) to your Launch library and returns its staticCreativeId. prepare_launch stages a Meta launch draft that you review and launch in the app; each ad can name a library id, a /videos render, or a file it adds to your library for you
  • Email: send_email sends real email immediately from a fixed StefanBrain sender, to up to 5 recipients per email and 50 recipients per 24 hours
  • Account: read-only account_status, and get_profile, which returns the account's id, email, and team name; ChatGPT uses it to label the connection. When api_wallet.reconciliation_required is true, wallet figures are provisional and REST requests billed to the API wallet are held for billing review.
  • Feedback: send_feedback tells the StefanBrain team where a tool or endpoint got in your way, and list_feedback returns your reports with the team's replies. Both are free. See Send feedback.

The web, Amazon, Google Trends, website-traffic, and Reddit tools appear only when their provider is configured. Every tool also accepts an optional context string, up to 2,000 characters, recorded in the account owner's audit log.

Not served over MCP: StefanBrain's knowledge corpus (knowledge_search, knowledge_read; use ask_stefanbrain instead), chat-only tools (chat_constraints, share_chat, request_connector_connect, collect_web_artifacts, capture_funnel), manage_automations (change schedules in the app), and the admin-only generate_hooks. Direct video analysis, cuts, and transcript tools are also excluded.

Put a hosted video URL in an ask_stefanbrain message when the agent should read it. Handshake, tools/list, get_profile, and job status, result, and cancel calls do not count against request limits. Each stage_file, send_feedback, or list_feedback call counts as a request but never draws on the plan pool or wallet. Calls that start work count and draw on the plan pool.

Poll a job

Submit tools return runId and status: "running". Call get_job_status with {"family": "<family>", "run_id": "<runId>"} plus the project and session you submitted with. When status is succeeded, failed, or cancelled, call get_job_result.

Toolfamily
create_images, edit_imagestatic_ad
find_anglesangle_finder
review_copycopy_chief
review_funnelcro_funnel_review
research_shortformshortform_research
get_meta_admeta_ad_lookup
Parked ask_stefanbrainmcp_ask

For a submit-tool job, get_job_result returns a result of {kind: "files", summary, files: [{path}]} for files saved in the job's chat, or {kind: "inline", summary, data}. A failed job carries its reason in error. Completed results also include artifacts and MCP resource_link blocks. Each artifact carries its path and an absolute download.uri that needs no authorization header. Copy download.uri exactly as returned; do not reconstruct its /files or /artifacts path. Completed ask_stefanbrain answers and their get_job_result reads list the files produced by that turn. scrape_social_comments returns the full CSV through the same grant mechanism in csvFile.downloadUrl. Links expire after 10 minutes. For asks and jobs, read the result again to renew them. Download scraper CSVs before their links expire. Credential revocation or file deletion withdraws access. Keep signed URLs out of logs and durable storage.

Stage a file inside an MCP client

Use one input lane for each stage_file call:

{
  "url": "https://example.com/brief.pdf"
}

Or send local bytes when the client supports base64 tool arguments:

{
  "base64_data": "JVBERi0xLjQK...",
  "filename": "brief.pdf",
  "content_type": "application/pdf"
}

The result includes upload_id, filename, content type, byte count, and expires_at. Uploads last 24 hours and can be reused across asks.

stage_file stages one file per call, up to 100 MB. MCP requests over 150 MB are refused with 413 request_too_large; host large files and pass url.

Audio and video files are rejected by both stage_file lanes. Host those files and include the URL in the ask message. To launch a video, stage an MP4 or MOV of up to 100 MB with POST /api/developers/v1/files and pass its upload_... id to prepare_launch as file, or pass a public https link.

Work in a chat or project

Each tool call runs in a real chat in your account. Clients that support custom headers can pin a default location:

x-stefanbrain-chat: chat_...
x-stefanbrain-project: proj_...

Without either header, StefanBrain uses the account's Developer API chat. A project header gives that project its own Developer API chat.

Connector clients that cannot set headers can address work through tool arguments:

  • project accepts a proj_... id or project UUID.
  • session creates or reuses a Developer API — <label> chat inside the resolved project.
  • ask_stefanbrain.chat accepts a concrete chat id or new.
  • get_job_status, get_job_result, and cancel_job accept optional project and session context; the job id and family identify your job.

Precedence is:

ScopeFirstThenDefault
ProjectTool project argumentx-stefanbrain-projectNo project
Chatask_stefanbrain.chat, then sessionx-stefanbrain-chatDeveloper API chat

There is no session header. Session labels use 1–128 characters from A–Z, a–z, 0–9, _, ., :, or -.

Poll or cancel with the returned job id and family from any chat or session on your account. Repeat the same project and session when retrying an idempotent submit. A call with an unused session label creates an empty Developer API — <label> chat.

Use query_projects to find accessible proj_... identifiers. Use get_project_context to retrieve a project's instructions and file roster. Pass a roster file_id to get a temporary download URL for the original file. Project files have no stored summaries or search index. Omit query; read an original with file_id. When the MCP connection is already pinned to a project, get_project_context can omit its project argument and use that pin.

An inaccessible project returns 404 project_not_found. A chat and project that do not match return 409 chat_project_mismatch.

A typical coding-assistant flow is:

query_projects → get_project_context → download an original with file_id → complete the grounded task

Send feedback

The server instructions tell your assistant to call send_feedback when a StefanBrain tool or endpoint fails, returns the wrong thing, or lacks something it needs. Send one report per problem, with the tool, the error text, and the run or chat id. The StefanBrain team reads every report and replies.

list_feedback returns the account's reports, newest first, each with its status and the team's reply. If the team replied to this account's reports in the last 14 days, the server instructions on the next connection end with up to 3 of those replies.

Each account can send 60 reports in any rolling hour. See Agent feedback for the fields, statuses, and errors.

Errors

A request-level failure returns an HTTP status and an error object with message, type, and code:

Statuscode
400invalid_chat or invalid_project from a header; invalid_project, invalid_session, conflicting_project, or conflicting_session from tool arguments
401unauthorized, with a WWW-Authenticate header for OAuth discovery
403api_key_scope_forbidden, api_key_suspended, or developer_access_forbidden
404project_not_found or chat_not_found
409chat_project_mismatch or chat_id_retired
413request_too_large
429A rate-limit code with Retry-After, or monthly_usage_limit_reached with resets_at
503workspace_busy or mcp_unavailable

A tool failure returns isError: true with the message in content and no structuredContent. Messages for invalid arguments and unknown tools begin with MCP error -32602.

Busy session asks run in a fresh chat and return session_chat_busy. Explicit busy chats steer on 2026-11-01 and refuse on 2026-10-20. Overlapping same-key retries return a typed busy conflict. See Handle a busy chat.

See Authentication for key scopes, Rate limits for limit codes, and Pricing for the difference between MCP and REST billing.

This documentation is built and hosted on Mintlify, a developer documentation platform.