> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Connect Claude, ChatGPT, Cursor, or any MCP client to your Aspect media library
Aspect hosts a remote [Model Context Protocol](https://modelcontextprotocol.io) server, so AI tools you already use can browse, search, and organize your media library directly:
```text theme={null}
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](/docs/api-reference) 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
1. In Claude Desktop or claude.ai, open **Settings**, then **Connectors**.
2. Click **Add custom connector**.
3. Paste the Aspect server URL: `https://api.aspect.inc/mcp`
4. Click **Connect** and sign in to Aspect when prompted.
1. Open **Settings** and turn on **Developer mode** (Connectors).
2. Add a new connector / MCP server.
3. Paste the server URL: `https://api.aspect.inc/mcp`
4. Sign in to Aspect when prompted.
1. Open **Settings**, then **MCP**, and add a new server (or edit `~/.cursor/mcp.json`).
2. Add the configuration below.
3. Sign in to Aspect when prompted.
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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. |
### Share links
| 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](/docs/api-reference) for these workflows.