StefanBrain
StefanBrain 的远程 MCP 服务器。通过 Claude、ChatGPT、Cursor 或 Windsurf 向 StefanBrain 提出请求,获取面向 DTC 品牌和付费广告团队的直接响应式 AI 平台提供的 Meta 广告钩子、广告文案、视频脚本、创意角度和研究。
托管 MCP 服务器
npx add-mcp 'https://stefanbrain.com/api/developers/v1/mcp'可安装到 Claude Code、Codex、Cursor 等客户端
文档
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_urlsfor JPEG, PNG, WebP, or GIF inputs. - Upload local images, PDFs, documents, and spreadsheets through
POST /api/developers/v1/files, then pass the returnedupload_...identifiers infile_ids. The upload needs an unscoped key or a key with therunsscope. A key scoped only tomcpgets403 api_key_scope_forbidden; callstage_fileinstead. - Call
stage_filewhen the MCP client cannot send raw HTTP. Stage a public URL or base64-encoded bytes, then pass itsupload_idinfile_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_idnames the run it joined. The returnedrun_idis 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 busyconflictwithrefusal.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.
| Client | Setup status | Long calls and Tasks |
|---|---|---|
| claude.ai / Claude Desktop remote connector | Unverified end to end; OAuth setup is documented. | Claude documents a 240-second call limit. Progress renewal and native Tasks are unverified in these hosts. |
| Cursor | Unverified end to end; configuration is documented. | The default deadline and native Task following are unverified. |
| Claude Code 2.1.312 | Verified local HTTP/stdio behavior; StefanBrain OAuth sign-in is unverified. | Foreground and ordinary background results work. |
| Codex CLI 0.165.0 | Verified 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 mode | Unverified 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 Copilot | Unverified end to end; released source implements MCP Tasks dated 2025-11-25. | Completion is unverified. |
| Gemini CLI 0.65.0 | Verified 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. |
| Windsurf | Unverified end to end; configuration is documented. | Deadline, progress renewal and native Task following are unverified. |
| Plain HTTP script | Verified 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
| Client | Documented setup steps | Verification |
|---|---|---|
| claude.ai / Claude Desktop remote connector | Open 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. |
| ChatGPT | Enable 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 clients | Add 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, andmanage_products - Research:
web_search,web_extract,agentcore_browser,website_traffic,amazon_search,amazon_product,google_trends,reddit_search,reddit_thread, andscrape_social_comments - Meta:
get_meta_adreads one public Ad Library ad as an asynchronous job.meta_ad_accounts_searchandmeta_ads_insightsare 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, andresearch_shortform - Jobs:
get_job_status,get_job_result, andcancel_job - Files:
stage_filefor a public URL or base64 payload that should become anupload_...id - Launch:
find_creativelists the images and videos you can launch, from your Launch library and your/videosrenders.upload_creativeadds one image or video (a public URL, a stagedupload_...id, or a file path in the chat) to your Launch library and returns itsstaticCreativeId.prepare_launchstages a Meta launch draft that you review and launch in the app; each ad can name a library id, a/videosrender, or afileit adds to your library for you - Email:
send_emailsends 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, andget_profile, which returns the account's id, email, and team name; ChatGPT uses it to label the connection. Whenapi_wallet.reconciliation_requiredis true, wallet figures are provisional and REST requests billed to the API wallet are held for billing review. - Feedback:
send_feedbacktells the StefanBrain team where a tool or endpoint got in your way, andlist_feedbackreturns 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.
| Tool | family |
|---|---|
create_images, edit_image | static_ad |
find_angles | angle_finder |
review_copy | copy_chief |
review_funnel | cro_funnel_review |
research_shortform | shortform_research |
get_meta_ad | meta_ad_lookup |
Parked ask_stefanbrain | mcp_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:
projectaccepts aproj_...id or project UUID.sessioncreates or reuses aDeveloper API — <label>chat inside the resolved project.ask_stefanbrain.chataccepts a concrete chat id ornew.get_job_status,get_job_result, andcancel_jobaccept optionalprojectandsessioncontext; the job id and family identify your job.
Precedence is:
| Scope | First | Then | Default |
|---|---|---|---|
| Project | Tool project argument | x-stefanbrain-project | No project |
| Chat | ask_stefanbrain.chat, then session | x-stefanbrain-chat | Developer 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:
| Status | code |
|---|---|
400 | invalid_chat or invalid_project from a header; invalid_project, invalid_session, conflicting_project, or conflicting_session from tool arguments |
401 | unauthorized, with a WWW-Authenticate header for OAuth discovery |
403 | api_key_scope_forbidden, api_key_suspended, or developer_access_forbidden |
404 | project_not_found or chat_not_found |
409 | chat_project_mismatch or chat_id_retired |
413 | request_too_large |
429 | A rate-limit code with Retry-After, or monthly_usage_limit_reached with resets_at |
503 | workspace_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.