adding-a-plugin

Adding a plugin

The repo is itself a Devin plugin: .devin-plugin/plugin.json lists every offering under optionalPlugins, and that file is the only thing consumers read. Two kinds of entry: "./plugins/<slug>" for a plugin authored here (every MCP server Devin hosts has one), and a { "source", "url", ["path",] "sha" } object for a third-party plugin pinned to an exact commit. Entries are sorted and each identity appears once; python3 scripts/validate.py enforces all of this and CI runs it.

An MCP server we host

1. Create plugins/<slug>/.devin-plugin/plugin.json, where <slug> is the marketplace server slug:
   • name is the slug; displayName is the server definition's name (the human title, e.g. "MySQL"); homepage, repository, and keywords come from the server definition too.
   • Write description as one action-oriented sentence about what users can do with the product and the value they get. Aim for 60–130 characters (about 200 maximum), without a trailing period. Expand on shortDescription; avoid filler such as "integration" or "MCP server".
   • Put requirements outside the install form and connection caveats in optional setup, immediately after shortDescription: {"notice": "...", "steps": ["..."]}. Use a one- or two-sentence notice and ordered setup steps without environment-specific URLs. At least one key is required; notice must be a non-empty string and steps a non-empty list of non-empty strings. No other keys are allowed. Only add setup for external steps or meaningful connection caveats. Do not repeat credential fields, placeholder names, OAuth sign-in instructions, or default domains already handled by the install form.
   • Check the brand mark in as plugins/<slug>/logo.svg (or .png/.jpg) and set "logo": "logo.svg" — a path relative to the plugin directory, as in Cursor's plugin format. Prefer this over an absolute https URL so cards never load images from a third-party host.
   • mcpServers declares the plugin's servers (usually one, keyed by the slug): command + args + env for stdio, or url (+ headers) for HTTP. A plugin that only ships skills/ omits it. Servers live only here: no .mcp.json, mcp.json or root plugin.json.
   • An HTTP server whose URLs differ only in the query (Supabase's ?read_only=true) may add urlOptions, a list of {label, url} that includes url. url stays the default; members pick another option in the server's settings. A url with a ${<NAME>} part a member types (Datadog's site, ${DATADOG_DD_MCP_DOMAIN:-mcp.datadoghq.com}) may list instead that URL with the part filled in, one option per value; members can still type a value no option lists.
   • Never check in a credential. Anything a user supplies is a plain ${<NAME>} placeholder, resolved from the credentials saved on the user's installation (no MCP_ prefix). A stdio env value must reference its own key ("AWS_PROFILE": "${AWS_PROFILE}") because a saved credential replaces the env entry with the same key; in args and headers the placeholder is the credential's only name.
2. Add "./plugins/<slug>" to optionalPlugins in .devin-plugin/plugin.json.

A third-party plugin

1. Review the vendor and the exact upstream commit you are endorsing.

2. Add an object to optionalPlugins:

   • whole repository: { "source": "url", "url": "https://github.com/<owner>/<repo>.git", "sha": "<40-hex>" }
   • plugin inside a repository: { "source": "git-subdir", "url": "...", "path": "<dir>", "sha": "<40-hex>" }

   Always pin a full 40-hex commit sha, never a branch or tag. Do not add display metadata; the plugin's own manifest at that sha supplies it. If we host the same integration ourselves, author it under plugins/ instead of pointing upstream.

Testing your plugin

validate.py only checks the manifest's shape; before opening a PR, install the plugin from your checkout and have a session call one of its tools (or use one of its skills).

• Locally: devin plugins install --local ./plugins/<slug>. The directory is used in place, so edits apply on the next session. Export any ${<NAME>} credential the server needs, then start devin and use it.
• In Devin Cloud, get it into Customize → Plugins at personal scope by any of: Add plugin → Upload .zip with a zip of plugins/<slug>; Add plugin → From repository with your fork and subdirectory plugins/<slug> (installs the fork's default branch); or a session on your branch where you ask Devin to install your plugin as a personal plugin (it uploads the directory, you approve). Then start a new session and have Devin call a tool or use a skill: an MCP that needs OAuth prompts you to authorize it in chat; one that needs a ${<NAME>} credential has to be connected first from the plugin's Connect button in Customize.

Both

1. Run python3 scripts/validate.py --fix to sort and format the manifest, then python3 scripts/validate.py --fetch to confirm upstream pins resolve.
2. To bump an upstream plugin, change its sha. To remove one, delete its entry (and its plugins/<slug> directory if it was authored here).
3. Consumers pin this repo by commit; after the change lands on main, bump their pin to the new sha.