Poly MCP Plugin

In this repo you can find instructions for how to install Poly within a variety of AI agent clients. This repo itself is usually enough to point your agent at, otherwise read below for more specific instructions.

Primer on Poly

Poly is a cloud file system with intelligent, embedding-powered search—store your files, find them by meaning, and chat with agents about them. Poly is available over the web, or via various desktop apps, or via agent integrations (like the one you're looking at). Poly contains the ability to "flashback" to any previous time period, down to the second, just by scrolling over a timeline. The Poly CLI is no different—it lets you list any folder at any time in the past, as well as read files at a particular revision as they looked at that time. Finally, Poly also lets you collaborate with other humans and/or agents with Shared Drives.

Integrating with Poly

This repo contains the official Poly plugin: the Poly MCP server configuration plus the poly-cli agent skill that teaches AI agents how to search, read, create, update, and organize files across your personal and shared drives.

Agents can use Poly in two ways:

• Poly desktop CLI (poly) — preferred whenever the agent runs on your machine. Ships with the Poly desktop app; talks to the local cache, works offline, and supports the full feature set including version history and rollbacks. To install the CLI, you must first install the Poly desktop app from https://poly.app (currently only available to waitlist users). The CLI is available in the Poly app's Downloads menu.
• Poly MCP server (https://mcp.poly.app/mcp) — a remote, more limited version of the CLI for web and cloud agents. Connects to your Poly account via OAuth.

The poly-cli skill tells the agent how to pick between them and how to use each one.

Installation & Setup

ChatGPT

Install Poly through the plugin marketplace:

1. Go to Plugins.
2. Click the chevron dropdown menu next to Create.
3. Add a marketplace with the URL: git@github.com:withpoly/polymcp.git (under "Source", leave other fields blank)

This installs the poly-official marketplace with a single app, Poly, which you should now be able to search for and add.

Note

You may need to restart the ChatGPT app for the Poly app to be detected correctly.

Codex

Ask Codex to add Poly as a skill and point it at this repository:

Add the Poly plugin as a skill from https://github.com/withpoly/polymcp

This repo follows the plugin marketplace structure (see .agents/plugins/marketplace.json), so it can also be added as a plugin marketplace with Poly as its single plugin.

Claude Desktop

Use the Poly Desktop Extension: open the Poly desktop app, go to the Downloads menu, and install the extension for Claude Desktop. This bundles the MCP connection and the skill with no manual configuration. Note that the .mcpb file is a simple local MCP server whose only purpose is to let the agent execute poly commands and nothing else. In order to use the desktop extension effectively, we recommend adding the Poly drive as a folder in Claude CoWork, while also giving the agent access to the extension, and turning off the remote MCP server. This way, Claude can edit and organize your files, or even do rollback operations for you.

Claude Code

Add this repo as a plugin marketplace and install the plugin:

claude plugin marketplace add withpoly/polymcp
claude plugin install poly@poly

Manual MCP-only setup

claude mcp add --transport http poly https://mcp.poly.app/mcp

Any MCP-native client

Any client that supports streamable HTTP can connect to the Poly MCP server directly:

• Server URL: https://mcp.poly.app/mcp (streamable HTTP)

Typical configuration:

{
  "mcpServers": {
    "poly": {
      "type": "http",
      "url": "https://mcp.poly.app/mcp"
    }
  }
}

Authentication is handled via OAuth on first connection.

Gemini CLI

gemini extensions install https://github.com/withpoly/polymcp

Then authenticate inside the CLI with /mcp auth poly.

Using the plugin

Once installed, just ask your agent about your files:

• "Search my Poly files for last quarter's planning docs"
• "Create a folder in my Poly drive and move these files into it"
• "Summarize the contents of the design folder in our shared drive"

If the agent runs on your desktop, make sure the Poly app is running and the CLI is installed (Poly app → Downloads menu). The agent will verify its connection with poly app root before doing real work.

Desktop vs. remote capabilities

Capability	Desktop CLI	Remote MCP
Search, list, read extracted text	✅	✅
Create, update, move, delete	✅	✅
Raw media access (audio/video/PDF bytes)	✅	❌ (extracted text/images only)
Folder history, restore, rollback	✅	❌
Deep folder copies	✅	❌
Bulk organization (dedupe, cleanup)	✅	⚠️ suboptimal — prefer the desktop app or a desktop agent

For heavy or complex operations, prefer the Poly desktop app or a desktop agent with CLI access (e.g. Claude CoWork, ChatGPT Work, or a local harness like Claude Code).

Repo layout

• .mcp.json — MCP server configuration pointing at https://mcp.poly.app/mcp
• server.json — MCP registry server manifest
• skills/poly-cli/ — the poly-cli agent skill
• .claude-plugin/, .codex-plugin/, .cursor-plugin/, .github/plugin/ — per-client plugin manifests
• .claude-plugin/marketplace.json, .agents/plugins/marketplace.json — the Poly plugin marketplace, with this plugin as its single entry
• assets/ — Poly logos and icons