Claude Code Plugin Integration with MCP Server — Practical Guide

Ready-made summary: This article walks you through installing the MCP server (Docker), creating a compliant marketplace.json plugin manifest, integrating a Claude Code plugin with the MCP server, developing locally, and submitting your plugin to a marketplace. Includes manifest examples, Docker commands, security notes, and a concise FAQ for voice queries.

---

Quick primer: what you need and the expected result

If you want your Claude Code plugin discoverable and runnable through an MCP-based marketplace, you must provide a valid marketplace.json manifest, host a stable HTTPS endpoint, and register that endpoint with an MCP server instance. The MCP server acts as the marketplace controller and plugin router; it’s often deployed via Docker for reliable, repeatable installs.

By the end of this guide you’ll have a minimal working setup: a Dockerized MCP server, a tested local Claude Code plugin that responds to requests, and a validated marketplace.json ready for submission. Think of it as moving from “it works on my machine” to “it works in production.”

We keep examples practical: exact Docker commands, a manifest template, endpoint best practices, and tips to pass automated marketplace validations.

---

Prerequisites and system architecture

Before you start, verify these essentials: an HTTPS-capable hosting environment (or a tunneling tool like ngrok for development), Docker (for the MCP server), a Claude-compatible plugin backend (HTTP endpoint), and an API key or auth model your plugin will use. You also need a valid domain or DNS alias if you intend to submit to an external marketplace—self-signed certs rarely pass review.

High-level architecture: the MCP server sits between the marketplace UI and your plugin endpoint. Users discover your plugin via the marketplace; when a user invokes it, the MCP server forwards structured requests (per the Claude Code plugin spec) to your plugin’s HTTP endpoint, enforces authentication and rate limits, and returns responses to the client. This separation enables centralized logging, permissioning, and manifest-driven discovery.

Minimum software stack:

• Docker Engine (or Docker Desktop) for MCP server deployment
• A TLS-terminated public URL for your plugin endpoint
• A JSON manifest file (marketplace.json) describing capabilities

---

Installing the MCP server with Docker

Deploying the MCP server in Docker is the fastest path. The server is typically published as a container image; replace the image name below with the appropriate repository/tag for your MCP build or distribution.

Example docker-compose (minimal) to run an MCP instance locally for testing. Save as docker-compose.yml:

version: "3.8"
services:
  mcp-server:
    image: mcp/server:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_LISTEN=0.0.0.0:8080
      - MCP_ENV=development
    restart: unless-stopped

Start it with:

docker compose up -d

After startup, verify the server health endpoint (example):

curl -sS http://localhost:8080/health | jq

For production, run behind a reverse proxy (Traefik/Nginx) with TLS termination. The MCP server configuration commonly supports integrations for authentication providers, storage backends, and plugin catalog sources—reference your MCP distro docs for environment flags. If using the sample above for local testing, tunnel the port via ngrok to obtain a public HTTPS URL for your plugin callbacks and external marketplace validations.

---

Creating a compliant marketplace.json manifest

The marketplace.json manifest is the contract between the marketplace and your plugin. It declares identity, endpoints, authentication requirements, supported content types, and capabilities. Marketplaces validate this manifest, so small errors block submission.

Key fields to include: id, name, description, version, endpoints (HTTP URLs for invocation and health), authentication (API key, OAuth), and scopes or capability descriptors. Keep the manifest minimal but explicit about required headers and payload formats.

{
  "id": "com.example.claude-plugin-weather",
  "name": "Weather Assistant (Claude Code)",
  "version": "1.0.0",
  "description": "Returns current weather and forecasts via Claude Code plugin API.",
  "endpoints": {
    "invoke": "https://api.example.com/claude/weather/invoke",
    "health": "https://api.example.com/claude/weather/health"
  },
  "authentication": {
    "type": "apiKey",
    "in": "header",
    "name": "X-Plugin-Api-Key"
  },
  "schemas": ["application/json"],
  "permissions": ["read:weather"]
}

Validation tips: ensure URLs use https, health endpoint returns 200 with a simple JSON payload, and the invoke endpoint accepts the expected Claude Code payload (usually a JSON structure containing messages and metadata). Use robust JSON linters and schema validators in CI before submission.

---

Integrating an MCP server with your Claude Code plugin

Integration is mostly about aligning request/response contracts and authentication flows. Typical flow: marketplace UI → MCP server → plugin invoke endpoint → plugin processes and returns structured response → MCP server forwards response to client. The MCP server may also handle verification challenges when you register your plugin manifest.

On your plugin side, implement these behaviors reliably:

• Accept POST requests with the Claude Code payload and respond within marketplace timeouts
• Validate incoming authentication (API key or OAuth token) and return meaningful HTTP statuses (401, 403, 429)
• Expose a light-weight health endpoint that checks dependency availability and returns JSON (e.g., {“status”:”ok”})

Testing locally: use a tunnel (ngrok) to expose your plugin endpoint over HTTPS and register the temporary marketplace.json with your local MCP instance. Trigger calls from a client or the marketplace UI and inspect both MCP server logs and plugin logs to ensure headers and payloads flow correctly.

---

Claude Code plugin development workflow and testing

Develop your plugin as a web service that supports JSON over HTTPS. Keep the service stateless where possible; stateful features can be achieved via external storage systems and session tokens. Use semantic versioning for your plugin to signal breaking changes to consumers.

Recommended local dev steps:

1. Start with a minimal invoke handler that returns a deterministic response for known inputs.
2. Add authentication checks, then integrate application logic and third-party APIs.
3. Implement health checks, logging, request tracing, and metrics early—these make marketplace reviews faster and production troubleshooting easier.

Automated tests to include in CI/CD: schema validation for responses, auth enforcement tests, rate-limit handling, and end-to-end tests using your MCP test instance. Use contract tests (consumer-driven) to ensure the marketplace/MCP expectations don’t drift from plugin behavior.

---

Submission checklist and marketplace best practices

Before you submit to a Claude Code plugin marketplace, run this checklist. Markets prioritize secure, well-documented, and stable plugins. Missing items are common reasons for rejection.

Marketplace reviewers will often run a smoke test invoking your plugin with sample payloads and check timeouts, error handling, and security. Provide a sandbox API key and sample requests in your developer documentation to speed up approval.

After approval, maintain a changelog, monitor usage metrics via the MCP server (rate limits, latency), and use CI to publish manifest updates automatically to the marketplace endpoint. Consumers appreciate clear deprecation notices and backward-compatible patches whenever feasible.

---

Security, compliance, and performance considerations

Security must be front and center. Authenticate via short-lived tokens or API keys with rotation, use TLS everywhere, validate and sanitize all inputs, and enforce strict CORS policies. Avoid exposing sensitive error details in public responses.

Performance: keep responses small and predictable. If your plugin performs long-running tasks, use async patterns and surface job status endpoints instead of blocking the invoke call until completion. Timeouts that exceed marketplace limits will be rejected or treated as failures.

Data governance: explicitly state what user data you persist and for how long. Provide a mechanism for users to request data deletion where applicable. This transparency reduces friction with marketplace compliance teams and with end users.

---

Semantic core (expanded keyword clusters for SEO & content mapping)

---

Backlinks and resources

Use the official marketplace registration flow and documentation when available. For an example manifest and a compatible MCP helper documentation, see this sample resource: Claude Code plugin marketplace example and MCP server plugin guide. If you need an MCP-specific helper, this resource provides templates and a manifest starter you can adapt.

If you want the manifest template or Docker setup prefilled, download the referenced example and modify the endpoints and authentication fields to match your environment before registering with a marketplace.

---

Micro-markup recommendation (FAQ & Article schema)

To increase the chance of rich results and to help voice-search crawlers, include structured data. Example JSON-LD for Article + FAQ is below — paste it into the <head> or near the top of your article.

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Claude Code Plugin Integration with MCP Server & Marketplace",
  "description": "Step-by-step guide to Claude Code plugin integration, MCP server setup, marketplace.json manifest, Docker install, development and submission.",
  "author": {"@type":"Person","name":"Developer Guide"},
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How do I install an MCP server with Docker?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Use a docker-compose manifest to run the MCP server image, expose port 8080 for local testing, and run behind a TLS reverse proxy for production."
      }
    },
    {
      "@type": "Question",
      "name": "What must a marketplace.json manifest include?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Include id, name, description, endpoints (invoke, health), authentication details, schemas, and permissions. Use HTTPS URLs and validate with a JSON schema."
      }
    },
    {
      "@type": "Question",
      "name": "How do I test my Claude Code plugin locally?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Expose your local plugin via an HTTPS tunnel (ngrok), register the temporary manifest with your MCP test instance, and run end-to-end calls while inspecting logs."
      }
    }
  ]
}

---

FAQ — three most common user questions

---

If you’d like, I can generate a ready-to-download marketplace.json tailored to your plugin name, example Docker compose for your specific MCP distribution, or a CI job that validates manifests automatically before submission. Want me to produce one now?