Tools, research and MCP

Use your Yunxin API key for managed tools. The dashboard provides Tools & research for execution and history, and Computer Use for paired browser environments. Administrators enable connections, prices and quotas under Tool services.

Discover and invoke

GET /v1/tools returns { "tools": [...] } with MCP name, description and inputSchema. Prices and availability are under _meta.yunxin. All providers and Yunxin tools use the same call endpoint:

POST /v1/tools/call
Authorization: Bearer YOUR_YUNXIN_API_KEY
Content-Type: application/json
Idempotency-Key: search-001

{"name":"web_search","arguments":{"provider":"tavily","query":"Tavily API documentation","max_results":5}}

Responses use MCP content, structuredContent and isError. The invocation id, status, data, sources and itemized usage are inside structuredContent. Get and cancel return the same envelope. isError: false also covers queued jobs; check status for completion. Reuse the idempotency key when retrying the same request. An optional max_credits limits initial admission; composite workflows also check their remaining budget before each step.

Included services cover Tavily search/extract/map/crawl, Brave and Exa search, Firecrawl and Jina readers, and Google Search/Maps grounded answers. Yunxin also provides multi-source search, document parsing, keyword knowledge search and structured extraction.

GET /v1/tool-invocations returns summaries and next_cursor. Pass that value as before for another page. Retrieve full results with GET /v1/tool-invocations/{id}.

Research jobs

Call deep_research with {"name":"deep_research","arguments":{"input":"Your research question","provider":"tavily"}}. Providers include google, tavily, perplexity, parallel and yunxin. The same endpoint returns a queued invocation promptly. Poll its detail endpoint for progress and the report.

POST /v1/tool-invocations/{id}/cancel cancels queued work. Yunxin research can stop at a step boundary; completed child calls remain billable. A hosted provider without post-dispatch cancellation returns 409 and continues to be tracked.

Unknown completion or missing metering remains visible as unknown or usage_pending. Credits remain reserved while reconciliation is needed. Composite details show the service fee, child-tool fees and model inference together. Hosted-provider estimates do not impose a hard upstream spending limit.

Unified format

Tool names identify capabilities: web_search, web_extract, web_read, website_map, website_crawl, search_grounding, maps_grounding, deep_research, document_parse, knowledge_search and structured_extract. Tavily, Brave and the other services are providers. Select arguments.provider, or omit it to use the administrator’s priority among available providers. Retries with the same idempotency key stay pinned to the original call.

_meta.yunxin.providers lists each provider’s prices, availability and optionsSchema; default_provider identifies the current default. Put vendor-specific parameters in arguments.provider_options, such as {"model":"mini"} for Tavily research. These options cannot replace common arguments or credentials. API-key tool grants use capability names.

HTTP and MCP share the MCP tool data structures. HTTP is a convenience interface; /v1/mcp provides the actual MCP protocol for existing clients. There are no provider-specific endpoints. Select a tool by name and follow its inputSchema; provider-specific data stays in structuredContent.data.

Yunxin adds invocation history, status, prices and budget controls. These are platform extensions, not MCP Tasks. HTTP authentication and invalid/admission requests return non-2xx errors with detail; accepted calls use the result envelope. failed and unknown set isError to true. The HTTP catalog includes permitted but unavailable tools; MCP discovery lists available tools.

MCP connection

For clients supporting Authorization headers:

{
  "mcpServers": {
    "yunxin": {
      "url": "https://YOUR_YUNXIN_HOST/v1/mcp",
      "headers": {"Authorization": "Bearer YOUR_YUNXIN_API_KEY"}
    }
  }
}

The endpoint supports stateless Streamable HTTP. Discover tools with tools/list, execute with tools/call, retrieve asynchronous results with get_tool_result, and cancel with cancel_tool_invocation (both accept invocation_id).

For custom API/internal hostnames, operators configure MCP_ALLOWED_HOSTS. Browser origins follow the frontend and explicit CORS configuration. This connection mode uses API-key headers.

Computer Use

Register a runner in Computer Use → Runners & setup, then follow its setup command and save the one-time token. The standalone client is python -m yunxin_runner; it needs no model or database credentials. Choose a vision/function-calling model and a paired runner to start a task.

Login and website verification pause automation. Complete the step in the visible browser, then resume with an optional instruction. Resume captures a fresh screenshot. The runner keeps a dedicated persistent profile and a durable action journal; uncertain actions are inspected rather than repeated after a restart.

Computer access requires an explicit computer_use or all-tools grant on the API key, plus access to the selected model. Existing keys do not automatically gain browser-control privileges.

With that grant, MCP also exposes computer_runners, computer_start_session, computer_get_session and computer_control_session. Starting a task requires a unique idempotency key. Only one active task runs on each runner.

Login data stays in the runner's profile. Screenshots and observations are sent to Yunxin and the selected model provider. Site verification can still reject an environment; a persistent profile is not a guarantee of access.

Import remote MCP providers

Administrators can add a Streamable HTTP server under Tool services → MCP providers, discover its tools, review their schemas and set prices before enabling them. Imported capabilities use custom.<name>; pass remote parameters inside arguments.input and select the server with arguments.provider. Legacy API keys do not automatically gain access to imported tools. Only reviewed, explicitly enabled tools are callable.

OAuth clients

Clients connecting to Yunxin can use OAuth discovery, S256 PKCE, refresh tokens and revocation. Configure the server's MCP_PUBLIC_URL. On the consent page, choose an existing API key whose permissions the client may use. The key itself is never shared. Disabling or rotating it invalidates the grant. Revoke individual clients under API & MCP.

Managed desktops and native engines

Computer Use now supports the shared vision/function gateway and native OpenAI, Claude and Gemini engines. Administrators configure each native engine's model and price. The Managed desktops tab can create a temporary server-side browser desktop when the operator enables the Docker runtime; select its runner when starting a task. Desktop creation, viewing and stopping are owner-scoped, and expiry is enforced automatically.

A user may have two desktops with lifetimes of 5–60 minutes. Desktop creation supports idempotent retries. Native model batches stop for provider-required confirmation or unknown usage; unsupported actions require inspection. The environment controls the browser viewport, not arbitrary host applications. Real upstream availability still depends on configured credentials and the provider account.