MCP server

Aspect hosts a remote Model Context Protocol server, so AI tools you already use can browse, search, and organize your media library directly:

https://api.aspect.inc/mcp

It is a Streamable HTTP MCP endpoint. Tools run through the same operation layer as the REST API and the in-app assistant, so behavior and permissions are identical everywhere.

Authentication

Two options:

OAuth sign-in: clients that support MCP OAuth (Claude, ChatGPT, Cursor, and others) prompt you to sign in to your Aspect account when you add the server. This is the easiest path.
API key: send an Aspect API key (sk_...) as a Bearer token in the Authorization header. Use this for clients or scripts that can attach explicit headers. See the API overview for how to create a key.

Either way, every tool call is checked against your own workspace, project, directory, collection, and asset permissions - the MCP server can never do more than you can.

Connecting a client

Claude
ChatGPT
Cursor
Other clients

In Claude Desktop or claude.ai, open Settings, then Connectors.
Click Add custom connector.
Paste the Aspect server URL: https://api.aspect.inc/mcp
Click Connect and sign in to Aspect when prompted.

Open Settings and turn on Developer mode (Connectors).
Add a new connector / MCP server.
Paste the server URL: https://api.aspect.inc/mcp
Sign in to Aspect when prompted.

Open Settings, then MCP, and add a new server (or edit ~/.cursor/mcp.json).
Add the configuration below.
Sign in to Aspect when prompted.

{
  "mcpServers": {
    "aspect": {
      "url": "https://api.aspect.inc/mcp"
    }
  }
}

Add Aspect as a remote (Streamable HTTP) MCP server and authorize with your Aspect account when your client prompts you:

{
  "mcpServers": {
    "aspect": {
      "url": "https://api.aspect.inc/mcp"
    }
  }
}

If your client does not support OAuth sign-in, configure an Authorization: Bearer sk_... header with your API key instead:

{
  "mcpServers": {
    "aspect": {
      "url": "https://api.aspect.inc/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_api_key"
      }
    }
  }
}

The same setup instructions are available in the web app under Settings → Agent & MCP, with copyable snippets per client.

Available tools

Workspaces

Tool	Description
`workspaces_list`	List workspaces available to you.
`workspaces_get`	Get a workspace you can view.
`workspaces_update`	Update a workspace you can edit.
`workspaces_users_list`	List people in a workspace, including roles and project permission counts.
`workspaces_users_add`	Add people to a workspace with workspace roles.
`workspaces_users_update`	Update workspace roles for people.
`workspaces_users_remove`	Remove people from a workspace, including their project permissions.
`workspaces_users_all_project_access_list`	List a person’s project access: effective roles, project defaults, and explicit overrides.

Projects

Tool	Description
`projects_list`	List projects in a workspace you can view.
`projects_get`	Get projects by ID.
`projects_create`	Create projects in a workspace you can edit.
`projects_update`	Update projects you can edit.
`projects_users_list`	List people with access to a project, including inherited versus explicit roles.
`projects_users_add`	Add people to a project with project roles.
`projects_users_update`	Update project roles for people.
`projects_users_remove`	Remove a person’s explicit project permission.

Directories

Tool	Description
`directories_list`	List child directories under a directory you can view.
`directories_get`	Get directories by ID.
`directories_create`	Create child directories under directories you can edit.
`directories_update`	Rename or recolor directories.
`directories_delete`	Move directories to the project trash.
`fs_items_move`	Move assets, directories, and symlinks to a destination directory.
`fs_items_copy`	Copy assets, directories, and symlinks into a destination directory via an asynchronous copy job.

Assets

Tool	Description
`assets_list`	List assets under a parent resource you can view.
`assets_get`	Get assets by ID.
`assets_update`	Rename assets (the new name must include the file extension).
`assets_delete`	Move assets to the project trash.
`assets_document_get`	Get the extracted per-page text of a document asset (PDF, slide deck, spreadsheet, and more).

Search

Tool	Description
`assets_search`	Search assets in a project using visual, transcript, document, and filename signals plus metadata filters; results include matched clip timing.
`assets_search_capabilities`	List a project’s search capabilities (available signal channels and filterable metadata attributes) for building search specs.

Transcription

Tool	Description
`assets_transcription_get`	Get an asset’s transcript, optionally scoped to a start and end time.

Collections

Tool	Description
`collections_list`	List collections in a project you can view.
`collections_get`	Get collections by ID.
`collections_create`	Create collections in projects you can edit.
`collections_update`	Update collections you can edit.
`collections_delete`	Delete collections where you have full access.
`collections_items_add`	Add asset or directory items to a collection.
`collections_items_remove`	Remove asset or directory items from a collection.

Metadata

Tool	Description
`metadata_attributes_list`	List metadata attributes available in a project, including custom fields.
`metadata_attributes_get`	Get metadata attribute details.
`metadata_attributes_create`	Create custom metadata attributes.
`metadata_attributes_update`	Update custom metadata attributes.
`metadata_attributes_delete`	Delete custom metadata attributes.
`asset_metadata_get`	Get custom metadata values for an asset.
`asset_metadata_set`	Set custom metadata values on an asset.

Comments

Tool	Description
`comments_get`	Get comment threads by ID, including replies.
`comments_search`	Search comments across a project.
`comments_create`	Create plain-text comments or replies, with optional video timestamps or document page numbers.

Tool	Description
`share_links_create`	Create share links for assets, directories, or collections you fully control.
`share_links_list`	List share links for one resource or a whole project.
`share_links_update`	Update share links you can manage.
`share_links_delete`	Delete share links you can manage.

Other

Tool	Description
`entities_list`	List labeled entities (such as recognized people) available for a workspace or project.
`notifications_list`	List your in-app notifications, including comments, mentions, and replies.

What MCP does not expose

Some operations are deliberately unavailable through MCP:

Uploads and downloads: no upload endpoints, download URLs, or storage tokens.
High-impact deletions: workspace create/delete and project delete are not exposed. Asset and directory delete tools move items to the project trash rather than permanently deleting them, and there is no empty-trash or permanent-delete tool.
Public share sessions: share password reveal and public share sessions are not available.

Use the REST API for these workflows.

Overview

API Endpoints

Authentication

Connecting a client

Available tools

Workspaces

Projects

Directories

Assets

Search

Transcription

Collections

Metadata

Comments

Other

What MCP does not expose

​Authentication

​Connecting a client

​Available tools

​Workspaces

​Projects

​Directories

​Assets

​Search

​Transcription

​Collections

​Metadata

​Comments

​Share links

​Other

​What MCP does not expose

Authentication

Connecting a client

Available tools

Workspaces

Projects

Directories

Assets

Search

Transcription

Collections

Metadata

Comments

Share links

Other

What MCP does not expose