> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/guides/using-the-shade-mcp-server.md). # Using the Shade MCP server Connect AI agents and MCP clients to a Shade workspace: endpoint, OAuth, client configuration, available tools, and building your own agent. The Shade MCP server lets AI agents work with a Shade workspace through the [Model Context Protocol](https://modelcontextprotocol.io/). An agent can search and browse drives, read assets and transcripts, update metadata, organize files, share links, and build custom objects and automations. This page is for developers. For step-by-step setup in Claude, ChatGPT, Cursor, and VS Code, see [The Shade MCP](https://academy.shade.inc/ai-tools/the-shade-mcp) in Shade Academy. ## Connection details | | | | ------------------ | -------------------------------------------------------------------------- | | **Server URL** | `https://mcp.shade.inc/mcp` | | **Transport** | Streamable HTTP. The server is stateless, so no session ID is needed. | | **Authentication** | OAuth 2.1 through Shade sign-in. API keys are not accepted. | | **Permissions** | The agent acts as the signed-in user and sees only what that user can see. | ## Add the server to a client Most clients only need the server URL. They open a browser for you to sign in to Shade the first time you use it. {% tabs %} {% tab title="Claude Code" %} ```bash claude mcp add --transport http shade https://mcp.shade.inc/mcp claude mcp list ``` {% endtab %} {% tab title="Codex CLI" %} Add this to `~/.codex/config.toml`: ```toml [mcp_servers.shade] url = "https://mcp.shade.inc/mcp" ``` Then sign in and check the connection: ```bash codex mcp login shade codex mcp list ``` {% endtab %} {% tab title="Cursor" %} Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects: ```json { "mcpServers": { "shade": { "url": "https://mcp.shade.inc/mcp" } } } ``` {% endtab %} {% tab title="VS Code" %} Add this to `.vscode/mcp.json`: ```json { "servers": { "shade": { "url": "https://mcp.shade.inc/mcp" } } } ``` {% endtab %} {% tab title="Claude and ChatGPT" %} Add a custom connector and paste `https://mcp.shade.inc/mcp` as the server URL. On Claude Team and Enterprise plans, an organization Owner adds the connector once under **Organization settings → Connectors**, and members connect from **Customize → Connectors**. {% endtab %} {% endtabs %} You can copy these configurations from **Settings → Integrate → MCP connections** in the Shade app. ## How authentication works The server follows the MCP authorization spec, so standard MCP clients handle sign-in on their own: 1. A request without a token gets a `401` with a `WWW-Authenticate` header pointing to `https://mcp.shade.inc/.well-known/oauth-protected-resource/mcp`. 2. That document names Shade's authorization server, `https://signin.shade.inc`. Its metadata is at `https://mcp.shade.inc/.well-known/oauth-authorization-server`. 3. The client registers itself (dynamic client registration and client ID metadata documents are both supported), then runs the authorization code flow with PKCE (`S256`). 4. The client sends the access token as `Authorization: Bearer ` on every request and refreshes it with the refresh token when it expires. The authorization server also supports the **device authorization grant** (`urn:ietf:params:oauth:grant-type:device_code`). Use it for agents that run without a browser, such as on a server or in CI: the agent shows a code, a person approves it in their browser once, and the agent receives tokens. {% hint style="warning" %} `sk_` API keys don't work with the MCP server. For scripts that don't need an AI agent, call the [REST API](/developers/using-the-api/using-the-api.md) directly with an API key instead. {% endhint %} ## Available tools | Tool | What it does | Changes data | | -------------------- | ----------------------------------------------------------------------------------------------------- | ------------ | | `list_workspaces` | List the workspaces the user belongs to | No | | `list_drives` | List the drives in a workspace | No | | `browse` | Navigate the folder tree of a drive | No | | `search` | Find assets, files, folders, collections, or views, including AI search over what's in the media | No | | `get_asset` | Get an asset's details and metadata | No | | `get_asset_previews` | Get preview images for an asset | No | | `get_transcript` | Read an audio or video transcript | No | | `get_download_url` | Get a signed download URL | No | | `find_duplicates` | Find duplicate files | No | | `manage_files` | Move, rename (including batch rename), copy, create folders, move to trash, or delete | Yes | | `manage_metadata` | Read a drive's fields, read and set values (including in bulk), create fields, and add select options | Yes | | `manage_collections` | List and create collections, and add or remove assets | Yes | | `manage_comments` | Read and add comments | Yes | | `manage_sharing` | List and create share links | Yes | | `manage_views` | Create, edit, and delete views | Yes | | `manage_objects` | Create, edit, and delete custom object types, fields, and records | Yes | | `manage_automations` | Create, edit, and delete automations, turn them on or off, and review runs | Yes | Most tools need a `driveId`. Agents get it by calling `list_workspaces`, then `list_drives`. Paths are relative to the drive root, for example `/Project/Ep 1`. The server doesn't upload files or read file bytes, and it doesn't mount drives. To move file contents, use `get_download_url`, or upload with the [S3 API or file system API](/developers/guides/uploading-to-shade.md). ## Build your own agent Any MCP client library can connect once you have an access token. This example uses the official MCP Python SDK (`pip install mcp`): ```python import asyncio import os from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client SHADE_MCP_URL = "https://mcp.shade.inc/mcp" async def main() -> None: headers = {"Authorization": f"Bearer {os.environ['SHADE_MCP_ACCESS_TOKEN']}"} async with streamablehttp_client(SHADE_MCP_URL, headers=headers) as (read, write, _): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print([tool.name for tool in tools.tools]) workspaces = await session.call_tool("list_workspaces", {}) print(workspaces.content[0].text) asyncio.run(main()) ``` To get the access token, use an OAuth library that supports the MCP authorization flow above, or the device authorization grant for headless agents. The official MCP SDKs include OAuth client helpers that handle discovery, registration, and refresh for you. ## Tips for reliable agents * **Start with discovery.** Have the agent call `list_workspaces` and `list_drives` before anything else, and reuse the IDs it gets back rather than guessing them. * **Prefer asset IDs over paths** for follow-up calls once the agent has found an asset. * **Prefer trash over delete.** Trashed files can be restored. Deleted files can't. * **Review automations before turning them on.** Automations created through the MCP start as drafts. Check them with `manage_automations` before setting them to active. * **Require approval for writes.** Most clients let you auto-approve read-only tools and ask before tools that change data. Use the "Changes data" column above to decide. * **Combine with other MCP servers.** With a project management or CRM server connected alongside Shade, an agent can pull a brief from one tool and gather matching assets into a Shade collection in a single step. ## Example prompts * "Find every interview clip in the Fall Campaign drive where someone mentions pricing, and add them to a new collection called Pricing Soundbites." * "List all files in /Deliverables uploaded this week that don't have a Status value, and set Status to Needs Review." * "Create an automation that emails a comment-only share link whenever a file is uploaded to /Rough Cuts." * "Pull our Notion content calendar and set it up as a custom object in Shade with the same fields." ## Related * [The Shade MCP](https://academy.shade.inc/ai-tools/the-shade-mcp): no-code setup for everyone on your team * [Integrating with Shade](/developers/get-started/integrating-with-shade.md): choose between the MCP server, REST API, S3 API, and webhooks * [Webhooks](/developers/guides/webhooks.md): react to changes an agent makes --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://academy.shade.inc/developers/guides/using-the-shade-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.