---
title: "Install a plugin bundle, add a custom MCP server, or upload a skill [write]"
method: POST
path: "/plugins"
---

# Install a plugin bundle, add a custom MCP server, or upload a skill \[write\]

`POST /plugins`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/plugins`
- Auth: HTTP bearer

multipart/form-data uploads a skill exactly as POST /skills did (one zip or individual files, SKILL.md at the root): its first revision, answered as {skill, revision}. source is github:owner/repo[/path][@ref] or a github.com URL to a folder in Claude Code's plugin format (.claude-plugin/plugin.json, skills/, commands/, .mcp.json). skills/<name>/ become workspace skills as they are and commands/<name>.md become skills whose SKILL.md is the command's prompt, all attached to every new session. Installing again updates in place: kept parts get a new revision, dropped parts are deleted (or switched off when a session holds them). Sub-agents, hooks and local MCP servers are listed under skipped. connectors lists each .mcp.json server, the AgentSky connector app it maps to, whether the caller has that connection, and the link to connect it.

## Request body

- union
  - object
    - `source` string, required
    - `mcp_tokens` object: Bearer tokens for the plugin's remote MCP servers, by server name. Write-only; stored sealed.
  - object: Add a custom MCP server: with `token`, a static_bearer secret in the workspace's default vault; with `agent_id`, the server on that agent. At least one. Answers PluginAddAnswer (201).
    - `mcp_url` string, required: https to a public host
    - `name` string
    - `token` string: Write-only
    - `agent_id` string

## Response `201`

Installed; a multipart upload answers {skill, revision}: the new skill:<id> plugin and its first revision

- object
  - `plugin` object
    - `name` string
    - `version` string, nullable
    - `description` string
    - `source` string
  - `skills` Skill[]
    - `id` string, required
    - `displayName` string, required
    - `latestRevisionId` string, nullable, required: What `latest` references resolve to.
    - `attachByDefault` boolean, required: Whether every new session in the workspace starts with this skill's latest revision.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `connectors` object[]
    - `server` string
    - `app` string, nullable
    - `transport` 'remote' | 'local'
    - `connected` boolean
    - `connect_url` string, nullable
  - `skipped` object[]
    - `part` string
    - `reason` string
  - `removed` object[]
    - `part` string
    - `result` 'deleted' | 'switched_off'

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/plugins/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)