# Artillect MCP

Подключите генерацию изображений, видео, аудио, 3D и другие доступные инструменты к MCP-клиенту. MCP использует тот же баланс, что Studio; возможности отдельных инструментов описаны в документации API.

## Подключение

URL Streamable HTTP: https://app.artillect.pro/mcp

Добавьте URL в настройки MCP вашего клиента и завершите OAuth в браузере. Альтернатива — Bearer API-ключ. Не передавайте ключ в промпте или публичной переписке.

```json
{
  "mcpServers": {
    "artillect": {
      "url": "https://app.artillect.pro/mcp"
    }
  }
}
```

## Примеры подключения

```bash
hermes mcp add artillect --url https://app.artillect.pro/mcp --auth oauth
hermes mcp login artillect
```

```bash
claude mcp add --transport http artillect https://app.artillect.pro/mcp
```

## Первая задача агенту

Вызови Artillect get_started, затем get_balance. Для генерации используй generate_image, возьми task_id/poll_args из ответа и вызывай get_task до done: true и непустого media_urls. После этого покажи каждый результат: inline image content уже считается доставкой; если есть writable workspace, дополнительно скачай каждый media_url, проверь файл и укажи абсолютный локальный путь. Для video/audio/mesh дай все ссылки явно. Не показывай результат только если я явно это попросил.

## Работа с генерациями

Начните с quickstart. Проверьте доступные модели, баланс и оценку стоимости; отправьте задачу и опрашивайте get_task до готового результата. Названия и схемы доступных инструментов сообщает MCP-сервер.

## Файлы пользователя: фото, видео, аудио и фото → 3D

User/chat files: request_user_upload → user drops image/video/audio files and presses Finish upload → get_user_upload until status=ready. Use files[].url in generate_image.input_urls, generate_video.start_image_url or the selected reference field, generate_mesh.image_url (image_urls for multiple ordered views), or generate_audio.audio_url/video_url where supported. The uploader is shared across modalities, including photo-to-3D; it does not accept 3D mesh files. Do not default to create_upload_url + shell PUT for a user photo.

Подробные рецепты доступны через get_started и MCP resource artillect://agent/recipes.

[Рецепты MCP в Markdown](https://app.artillect.pro/docs/mcp/recipes.md)

[Поиск по публичной базе знаний](https://app.artillect.pro/knowledge/#knowledge-search)

## Sandbox network FAQ

**First action for “make a 3D model from my photo”:** request_user_upload → wait for the user to upload and press Finish upload → get_user_upload status:ready → generate_mesh with image_url → get_task → labelled GLB link. Do not test shell connectivity, mint a presigned PUT, install software or demand network settings before trying this supported path. Uploading and generation are different steps; say what the tools actually confirmed.

### Before uploading: do I have the reference?

- **I can see the photo in the conversation. Can I upload what I see?** Seeing an image does not prove you have its original bytes or a readable file path. If your host exposes an actual file, that is a separate capability; do not assume a Windows path is readable in a Linux VM or by hosted MCP. Default to the widget for a user attachment. Explain simply: “Please drop the original photo into this upload card and press Finish upload so Artillect can use it as the reference.” Do not ask for Blender or an API key in chat.
- **Will uploading again charge for another generation?** Uploading is not generation submission. It is subject to file/storage limits; generate_mesh is the token-spending step. Check balance/model estimate and avoid promising every operation is free. A failed download does not require a new generation.
- **Should I turn the visible photo into a text-to-3D prompt instead?** No. A user asking for a model from their photo expects image-to-3D. Use a supported i2m model and image_url. A prompt describing the photo is not a replacement for the source file; do not silently switch to t2m or add conversion/rigging/animation tasks the user did not request.
- **Does “same S3 as Studio” mean I must access S3 myself?** No. It describes where Artillect stores media, not a required client network path. The widget and server handle storage; the agent passes returned URLs between MCP tools. Reuse an already-ready Artillect media URL directly instead of downloading and re-uploading it.
- **Which uploader applies to 3D/audio?** The file kind and the output modality are separate. A photo for 3D is an image upload; audio/video inputs use the same widget when the chosen model supports them. Use list_models for actual input fields and constraints. There is no requirement for a dedicated “3D uploader” to accept a photo.

### Network and host capabilities

- **MCP works, but PUT/download returns 403. Is Artillect broken?** These are separate network paths: MCP tool transport, the user's browser/widget, and agent shell/VM HTTP. An explicit proxy denial identifies a host network restriction; a bare HTTP 403 alone does not. Check the failing operation, response body/headers and Artillect request_id when available. An Artillect permissions error or an expired/invalid S3 presigned signature needs a different fix. Do not claim which domains a host allows without evidence. Report MCP/API failures with submit_feedback; never include API keys, upload tickets or signed URL query strings.
- **Do I need app.artillect.pro and s3.ru1.storage.beget.cloud in an allowlist?** Not for the standard user-file upload and generation flow: call request_user_upload, then get_user_upload; the widget transfers the file through the user's browser or its host bridge, not your shell PUT. A returned media URL can be submitted to generate_* without downloading it. The S3 hostname here is an example from a reported failure, not a permanent endpoint: use the URL actually returned by the tool. The widget can still have its own host/CSP restrictions; shell connectivity does not diagnose those.
- **Should the user change Admin settings → Capabilities?** Do not prescribe that menu as a universal fix. Network controls belong to the host, not Artillect, and their names, availability and policy vary. Only investigate the host's actual network controls if the user explicitly requests local processing that needs direct HTTP. Ordinary photo-to-3D needs neither a shell allowlist change nor Blender, a second VM or a VPN. Do not promise a particular process or VM has unrestricted internet.
- **If shell cannot GET the image URL, can Meshy still use it?** Yes, shell access is not a prerequisite for submitting a ready URL through MCP; Artillect/provider input handling happens outside that shell. Submit the exact ready URL in the model's input field. Do not change the hostname, strip signed query parameters, preflight it with curl or attach your API key to storage URLs. If generate_mesh actually returns an input-fetch error, investigate that error rather than assuming success or blaming the shell.
- **If a VM also gets 403, does that prove Blender will work?** No. It only describes those observed requests. The screenshot's claim that Windows/Blender has full internet is not a guarantee or a product requirement. A different process can share the same proxy or lack the user's file. Do not move credentials or executable scripts into unrelated applications to solve an ordinary upload.
- **Are MCP capabilities, widget CSP and Admin Capabilities the same setting?** No. MCP capabilities advertise tools/resources/extensions; widget CSP governs requests made by the embedded app; a host's network policy governs shell/VM egress. Do not treat a successful MCP handshake as proof of shell internet, or a denied curl as proof that MCP Apps are unavailable. Use the observed error from the specific channel.

### Use the supported upload path

- **Photo attachment → 3D: where is the uploader?** It is the same request_user_upload widget as for image/video/audio. Call it with expected_count:1 (or the required number of ordered views), wait for get_user_upload status:ready, then use files[0].url as generate_mesh.image_url; for multi-view use files[].url as image_urls and a supported multi-i2m model. A chat image is not file bytes: do not reconstruct it as base64 or replace it with a guessed text description. Pass project_id when the user explicitly chooses a project; do not assume upload alone submits generation.
- **Must I call finalize_upload after the widget?** No. Ready widget files are already usable. finalize_upload belongs only to create_upload_url → successful direct PUT → finalize_upload. Use that path for integrations with actual bytes and confirmed HTTP access, not as the default for a chat attachment. If PUT is blocked, switch to the widget rather than repeatedly finalizing an absent upload.
- **I already minted a presigned URL and PUT failed. What now?** A URL or pending asset_id does not prove bytes arrived. Stop retrying the blocked shell PUT; do not finalize an absent object or tell the user that upload completed. Use request_user_upload and the ready URL from its new ticket. If a PUT really succeeded but finalize fails, keep its asset_id and investigate the actual finalize error; do not assume that widget completion needs this finalize tool.
- **The widget says collecting or pending. Can I submit now?** No. Ask the user to finish the card, wait for status:ready and use the completed ordered batch. Do not silently generate from a partial batch. A widget request only renders a card; it is not a completed upload. If the ticket expired, request a new one. Do not claim “I uploaded your photo” unless the ready response confirms it.
- **The user named a project. Does upload project_id choose generation billing too?** Pass the chosen project_id explicitly to the generation as well; the upload ticket destination alone does not configure the next tool. Resolve the named project with list_projects and follow returned access/billing information. Do not invent a project ID or promise a particular payer without that evidence.

### Poll, deliver and recover without duplicate work

- **Submit returned task_id but a later request failed. Start over?** No. Retain task_id and resume get_task with the returned poll_args. A polling or download failure does not invalidate an accepted generation. If submit itself had an uncertain outcome, retry with the same idempotency_key and original parameters rather than changing the key and risking another charge. Do not submit again merely to obtain a different download URL.
- **Status looks completed but result URLs are empty. Is it time to use the provider CDN?** No. Follow the returned hint/recommended_poll_interval_sec and poll for the stable Artillect artifacts. Do not guess a GLB URL, download temporary provider URLs or announce a file you have not received. If the task is failed/cancelled or reports an actual error, handle that state; “keep polling for assets” applies to finalizing output, not every failure.
- **Must I download the GLB?** No. Poll get_task until completed with non-empty media_urls and give every resulting GLB/other artifact URL as a labelled clickable link. Do not turn successful generation into a failure because your shell cannot fetch it. Blender/conversion is a separate step only if the user requested editing or another format; do not promise OBJ or PBR textures from every model. Local download is needed only for requested local processing or delivery.
- **A clickable GLB link was returned. Is the user's original request complete?** For “make a 3D model from the photo”, deliver every returned artifact with a clear label; successful generation and a working user download are separate observations. Do not claim you downloaded, opened or inspected the model unless you did. A blocked agent download does not prove the user's browser link is broken. If the user reports a browser download error, investigate that actual response instead of asserting it is the sandbox.
- **Do I need OBJ + PBR textures?** Only if the user requested them. Return the formats the task actually produced. Check model options and returned artifacts before promising textures; a GLB-to-OBJ conversion is a separate local-processing request, not a prerequisite for image-to-3D. If requested conversion needs bytes and the agent's HTTP is blocked, deliver the existing model and explain the specific remaining conversion limitation without claiming generation failed.
- **What should I tell the user after a shell proxy denial?** Say: “My direct file transfer was blocked. I'll use the Artillect upload card; please drop the photo there and press Finish upload.” If generation already completed, give its result link instead. Do not lead with demands to whitelist domains, enable Capabilities or install/run Blender. If the widget is also unavailable, explain that observed limitation and offer the Studio/public-URL fallback below.
- **Widget missing or failing?** Call request_user_upload rather than assuming image-to-3D lacks a widget. If the host cannot render MCP Apps, ask the user to upload in Artillect Studio and provide its usable media URL, or use upload_file({url}) for an existing public HTTPS file. If a visible widget reports an upload error, preserve its actual error/request_id and report it; do not infer shell allowlist failure. Do not invent a local file path, signed URL or image bytes. get_user_upload status:collecting is not ready: the user must press Finish upload. If a ticket expires, request a new one.


[Public API: параметры и ограничения](https://app.artillect.pro/docs/artillect-api.md)

[Возможности интеграций](https://app.artillect.pro/docs/artillect-features.md)

[Примеры сценариев](https://app.artillect.pro/docs/artillect-use-cases.md)

Страница: [Открыть сайт](https://app.artillect.pro/docs/mcp/)