Agent Plugin

Cosmic's MCP server and Agent Skills packaged as a single Agent Plugin, targeting spec version 1.0.0. Install it once and your coding agent gets Cosmic's content tools plus the skills that teach it how to use them, in Cursor, VS Code, GitHub Copilot, and Kiro.

Agent Plugins is an open, vendor-neutral specification for bundling MCP servers, skills, and prompts into one directory so the same package loads in every conformant client. The plugin contains no product code of its own: it configures the same @cosmicjs/mcp server and documents the same @cosmicjs/sdk you can already use by hand. What it saves you is the setup: one install instead of hand-editing a different config file for every editor you work in.

What the plugin includes

Two MCP servers and two skills.

cosmic is the working server. It runs locally over stdio via npx @cosmicjs/mcp, reads your bucket credentials from the environment, and exposes the full bucket toolset:

Reads work with a read key alone. Create, update, delete, upload, and AI generation require a write key. See the MCP Server docs for what each tool does and when an agent should reach for it.

cosmic-signup is the bootstrap server, hosted at mcp.cosmicjs.com/v1/agent over Streamable HTTP. It takes no credentials at all and exposes cosmic_agent_signup, cosmic_agent_verify, and cosmic_agent_status, so an agent on a machine that has never heard of Cosmic can provision a project. See the two servers for when each one applies.

Skills load alongside the tools, so the agent gets the tool and the guidance for using it well at the same time:

• cosmic-sdk covers objects, queries, media, imgix transforms, and AI generation with the JavaScript and TypeScript SDK, plus provisioning a project when the user has no credentials yet.
• cosmic-content-modeling covers object types, the metafield type table, validation rules, relationships, and rich-text fields.

Install

Cursor

Clone the repository and link it into your local plugins directory:

git clone https://github.com/cosmicjs/cosmic-agent-plugin.git
ln -s "$PWD/cosmic-agent-plugin" ~/.cursor/plugins/local/cosmic

Restart Cursor or run Developer: Reload Window. See the Cursor plugins reference.

VS Code

Set chat.plugins.enabled to true, then run Chat: Install Plugin From Source from the Command Palette and enter:

https://github.com/cosmicjs/cosmic-agent-plugin.git

To load a local checkout instead, use the chat.pluginLocations setting:

{
  "chat.pluginLocations": {
    "/absolute/path/to/cosmic-agent-plugin": true
  }
}

VS Code reads the portable skills/ directory and mcp.json directly. See the VS Code Agent Plugins docs.

GitHub Copilot

copilot plugin install cosmicjs/cosmic-agent-plugin

Or run /plugin install inside an interactive session. To enable it for a repository instead, add it to enabledPlugins in .github/copilot/settings.json, which is also the only form the Copilot cloud agent supports. See the CLI plugin reference.

Kiro

Kiro calls these "powers" and follows the Agent Plugins spec. In the Powers panel, choose Add Custom Power → Import power from GitHub, enter https://github.com/cosmicjs/cosmic-agent-plugin, and select Install. Import power from a folder loads a local checkout instead. See the Kiro powers docs.

Kiro manages MCP servers internally rather than writing to ~/.kiro/settings/mcp.json, and it namespaces server names, so the cosmic server appears prefixed.

ChatGPT and Codex

Not supported through this package yet. OpenAI's plugin documentation specifies a .codex-plugin/plugin.json manifest and a .mcp.json MCP config, neither of which is the portable Agent Plugins layout. Until that changes, configure the Cosmic MCP server directly as described in the MCP Server docs.

Any conformant client

Every conformant client loads a plugin from a directory containing plugin.json, so cloning the repository and pointing your client at the directory works generally:

git clone https://github.com/cosmicjs/cosmic-agent-plugin.git

Credentials

The cosmic server reads its credentials from the environment. The plugin itself declares none, and contains no key or bucket slug.

Find all three in your dashboard under Bucket → Settings → API Access.

export COSMIC_BUCKET_SLUG=your-bucket-slug
export COSMIC_READ_KEY=your-read-key
export COSMIC_WRITE_KEY=your-write-key   # omit for a read-only install

Agent Plugins v1 has no portable mechanism for supplying a secret to a plugin. Configured env values in mcp.json are visible package data, and clients expand only ${PLUGIN_ROOT} and ${PLUGIN_DATA}, never ${COSMIC_READ_KEY}. So you supply credentials one of two ways:

1. Export them in the environment your client inherits, through your shell profile, a launch agent, or the client's own environment settings. This is the portable option.
2. Set them in your client's native MCP configuration, which sits outside the Agent Plugins format but is supported by every client above.

Verify the install

Ask your agent:

List the object types in my Cosmic bucket

A list of your content models confirms that both the server and your credentials are working. To check that the skills loaded too, ask something that needs modeling guidance rather than a tool call:

Add a Products object type with a name, price, description, and image

The two servers

The plugin declares two MCP servers because Cosmic's two hosted scopes have opposite credential requirements, and only one of them can be expressed portably.

cosmic-signup is remote. https://mcp.cosmicjs.com/v1/agent is one fixed URL for every user and needs no credentials, which satisfies the spec's rules for remote servers with nothing left over.

cosmic is stdio, because the hosted bucket endpoint cannot be expressed portably. Its URL embeds the bucket slug (https://mcp.cosmicjs.com/v1/buckets/{bucket-slug}) and it authenticates with an Authorization header, while the spec forbids placeholder and environment expansion in url and headers, and forbids credentials in headers outright. A remote entry would therefore mean publishing one customer's bucket slug and key in a public repository. Running the same server locally over stdio keeps your credentials in your own environment.

To use the hosted bucket endpoint anyway, configure it directly in your client as described under Hosted MCP.

Which server an agent should use

Prefer cosmic whenever COSMIC_BUCKET_SLUG and COSMIC_READ_KEY are set. Reach for cosmic-signup only when they are not. A freshly provisioned bucket starts restricted: 50 objects, 5 MB of media, no AI credits, and hard-deleted after 14 days unless the human completes the emailed verification. The cosmic-sdk skill documents the whole flow, including the OTP the human has to relay back, and Agent Skills covers it in full.

Clients that implement only stdio will skip cosmic-signup and load everything else.

Plugin vs MCP server vs Agent Skills

The plugin is a distribution format, not a fourth product. It is the same MCP server and the same skills, bundled so they install together.

Install the plugin if you work in Cursor, VS Code, Copilot, or Kiro and want both at once. Configure the MCP server directly if you want the hosted endpoint, are using a client the plugin does not cover, or need the agent scope on its own.

Resources

• MCP Server
• Agent Skills
• CLI
• Discord Community