Skip to main content

The client cannot connect

Use https://api.aspect.inc/mcp and select Streamable HTTP. This is the media platform server. A documentation-search MCP offered by the docs site serves a different purpose. Refresh or restart the client connection after changing its configuration. For OAuth, complete the Aspect sign-in. For an API key, check that the client sends the key as a Bearer token without exposing it in a prompt or log.

Connected, but the project is missing

Ask for workspaces_list, then projects_list for the expected workspace. Check the signed-in account and its permissions. Knowing an asset ID does not grant access to it. When combining MCP with the CLI, also run aspect auth status --json. They authenticate separately and can be signed in as different accounts.

Search or transcripts return no content

Check the project ID and use assets_search_capabilities to discover valid search channels and filters. Verify that the source is uploaded and processed. Indexed captions, transcripts, or document text may not exist yet, and a selected time range or track can have no entries. Try a known filename or list the containing directory to distinguish missing access from a search query with no matches.

A copy or generation returned an ID, but no file is ready

A job or run ID records accepted background work. It is not a completion signal. Inspect the copy destination and expected files; use generations_run_wait to wait for a generation, or generations_run_get for a one-off check. Check for processing errors before starting dependent work. For generation, read IDs from the returned runs list. Continue waiting while finished is false, then check each run’s state: a failed run also counts as finished. Completed media runs return output_asset_id; text runs return output_text instead of a file. Do not submit the same request again just because a wait timed out. For local CLI work, aspect transfer status <id> --json reports detached transfers, while aspect pin list --json reports offline pins. These are different systems; a cloud copy job ID is not a CLI transfer ID.

Canvas nodes exist, but nothing is generating

Creating nodes and connections prepares the graph. Call generations_run for each node you want to execute, with both canvas_id and node_id, its stored prompt, and its model choice. Run source nodes first and wait for their outputs before submitting dependent nodes. For a canvas run, inputs come from incoming connections. Do not pass explicit inputs. A text node is a standalone note and cannot feed a generation; use text_gen when generated text should become prompt context. See Canvases and generation.

Auto rejects a run or uses different settings

Supply exactly one of auto_tier or model_id. An Auto run without a canvas node also needs modality; a run on a canvas node must omit it. Auto can adjust requested settings to values its selected model supports. Inspect the returned model_id and params for what ran. If no compatible model accepts all inputs together, the call reports why. Check the source types, input count, clip specifications, and whether each source has a usable output. For a named model, inspect its param_schema, input_handles, and limits with generations_models_list; pass its ID in model_ids to include its clip specifications (input_specs). For endpoint frames on an Auto video node, set frame_slot on the connection. An image without a frame slot is treated as a reference image, and a last frame requires a first frame. Use the completed run’s output_asset_id with assets_get to find the file’s actual path. One-off media outputs are stored in Aspect Stash; canvas media outputs are in the canvas’s folder inside that stash. A text run returns output_text and does not create a media file. Prefer the Aspect CLI or a mounted project for downloads. If using assets_download_url_get because the CLI is unavailable, request a new URL after url_expires_at. The preview variant is a thumbnail; choose original for the full file or stream_proxy for a viewing copy when available. Download permission is required.

The agent cannot copy proxies, mount files, or edit a timeline

Pass copy_as_proxy: true to fs_items_copy, the same option as Aspect’s Copy videos as proxies action; see Agentic Video Editing. Mounts, local transfers, and pins use the CLI. Timeline edits use the editor’s own integration. Connecting Aspect MCP alone does not install an editor integration or make a local drive available to a cloud-only agent.

A tool is missing or rejects an argument

Refresh the connection and inspect the tools and input schemas your client actually exposes. Client prefixes can differ from the names in the tool reference. Use a returned resource ID, respect required fields, and remove arguments that are not in that tool’s schema. Batch operations where a list is supported. For large libraries, follow the tool’s pagination instead of increasing the request indefinitely.