# Tools, research and MCP (/docs/tools-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 [#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:

```http
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 [#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 [#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](https://modelcontextprotocol.io/specification/2025-11-25/server/tools). 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 [#mcp-connection]

For clients supporting Authorization headers:

```json
{
  "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 [#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 [#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 [#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 [#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.