Upbound Marketplace MCP Server

A Model Context Protocol (MCP) server that provides AI agents with access to the Upbound Marketplace API. This server enables agents to search, discover, and manage marketplace packages and repositories, with a focus on helping users leverage marketplace resources for Crossplane compositions and package management.

Built using the mcp-go framework for robust MCP protocol compliance and performance.

Features

• Package Search: Search for packages across the Upbound Marketplace with advanced filtering
• Package Metadata: Get detailed information about packages including CRDs, examples, and documentation
• Asset Access: Retrieve package assets like CRDs, examples, docs, and package files
• Repository Management: Browse and manage repositories
• Authentication: UP CLI-based authentication for accessing private resources
• Multi-API Support: Supports both v1 and v2 marketplace APIs
• Composition Focus: Specialized tools for working with Crossplane compositions and functions

Installation

Quick start (recommended): run once as a long-lived HTTP server

This is the supported pattern for all MCP clients that can talk to an HTTP
endpoint (Cursor, Claude Code, Cline, Continue, Zed, etc.). The server runs
detached in a single container; any MCP client connects to it over HTTP. No
container is started or stopped per MCP session, so there is nothing that
can leave a broken container behind.

1. Log in with the UP CLI so the server has a session to reuse:

   up login
   

2. Start the server once, detached. Replace the .up path with your actual
   UP CLI config directory (see UP CLI config location below).

   docker run --name mcp-marketplace --rm -d -p 8765:8765 \
     -v "$HOME/.up:/mcp/.up:ro" \
     xpkg.upbound.io/upbound/marketplace-mcp-server-http:v0.1.0
   

   Verify it is serving:

   curl -s -X POST http://localhost:8765/mcp \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

3. Point your MCP client at it:

   {
     "mcpServers": {
       "marketplace": {
         "httpUrl": "http://localhost:8765/mcp"
       }
     }
   }
   

UP CLI config location

• macOS / Linux: ~/.up (e.g. /Users/you/.up or /home/you/.up)
• Windows: %USERPROFILE%\.up

Upgrading to a new image version

docker pull xpkg.upbound.io/upbound/marketplace-mcp-server-http:<new-tag>
docker rm -f mcp-marketplace
docker run --name mcp-marketplace --rm -d -p 8765:8765 \
  -v "$HOME/.up:/mcp/.up:ro" \
  xpkg.upbound.io/upbound/marketplace-mcp-server-http:<new-tag>

Alternative: stdio transport (for clients without HTTP support)

Some MCP clients (including older Claude Desktop builds) only support stdio
transport and launch the server as a subprocess per session. In that case use
the stdio image — but do not pass --name. A fixed container name can
only ever be held by one container at a time, so if a previous session's
container is still alive (client crash, lost stdio, --rm not firing) every
new session will fail with
Conflict. The container name "/mcp-marketplace" is already in use.
Let Docker generate a unique name per session instead:

{
  "mcpServers": {
    "marketplace": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/your-username/.up:/mcp/.up:ro",
        "xpkg.upbound.io/upbound/marketplace-mcp-server:v0.1.0"
      ]
    }
  }
}

Replace /Users/your-username/.up with your actual UP CLI config directory.

Building from source

git clone https://github.com/upbound/marketplace-mcp-server.git
cd marketplace-mcp-server
go build ./cmd/mcp-server   # stdio binary
go build ./cmd/mcp-http     # HTTP binary

Or build images locally:

docker build --target stdio -t marketplace-mcp-server:latest .
docker build --target http  -t marketplace-mcp-server-http:latest .

HTTP API reference

The HTTP transport serves JSON-RPC 2.0 at http://localhost:8765/mcp in
stateless mode (no initialize handshake required). Example calls:

# List available tools
curl -X POST http://localhost:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

# Search for packages
curl -X POST http://localhost:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "search_packages", "arguments": {"query": "aws", "size": 5}}}'

Troubleshooting

Conflict. The container name "/mcp-marketplace" is already in use

This comes from using --name mcp-marketplace in a stdio MCP client config.
--rm only fires on a clean exit; if the client crashes or is force-quit,
the container lingers and the next session can never reuse the name.

Fix: follow the Quick start above (HTTP, one long-lived container),
or if you must use stdio, remove --name from your MCP client config and
let Docker assign a unique name per session.

If you're already stuck, remove the lingering container once and restart
your MCP client:

docker rm -f mcp-marketplace

no authentication token loaded / 401 responses from the marketplace

The server reads your session from the UP CLI config mounted at
/mcp/.up/config.json. Make sure:

• up login has been run on the host and the session hasn't expired
• the -v "$HOME/.up:/mcp/.up:ro" mount points at the same directory
• if you switched up profiles while the server was running, call the
  reload_auth tool from your MCP client (no container restart required)

Available Tools

1. search_packages

Search for packages in the Upbound Marketplace.

Parameters:

• query (string): Search query for packages
• family (string): Family repository key to filter by
• package_type (string): Type of package (provider, configuration, function)
• account_name (string): Account/organization name to filter by
• tier (string): Package tier (official, community, etc.)
• public (boolean): Filter by public/private packages
• size (integer): Number of results to return (max 500, default 20)
• page (integer): Page number (0-indexed, default 0)
• use_v1 (boolean): Use v1 API instead of v2 (default false)

Example:

{
  "name": "search_packages",
  "arguments": {
    "query": "aws provider",
    "tier": "official",
    "public": true,
    "size": 10
  }
}

2. get_package_metadata

Get detailed metadata for a specific package.

Parameters:

• account (string, required): Account/organization name
• repository (string, required): Repository name
• version (string): Package version (optional, gets latest if not specified)
• use_v1 (boolean): Use v1 API instead of v2 (default false)

Example:

{
  "name": "get_package_metadata",
  "arguments": {
    "account": "upbound",
    "repository": "provider-aws"
  }
}

3. get_package_assets

Get assets (documentation, icons, release notes, etc.) for a specific package version.

Parameters:

• account (string, required): Account/organization name
• repository (string, required): Repository name
• version (string, required): Package version or 'latest'
• asset_type (string, required): Type of asset (docs, icon, readme, releaseNotes, sbom)

Example:

{
  "name": "get_package_assets",
  "arguments": {
    "account": "upbound",
    "repository": "provider-aws",
    "version": "latest",
    "asset_type": "docs"
  }
}

4. get_repositories

Get repositories for an account.

Parameters:

• account (string, required): Account/organization name
• filter (string): AIP-160 formatted filter (v2 only)
• size (integer): Number of results to return (default 20)
• page (integer): Page number (0-indexed, default 0)
• use_v1 (boolean): Use v1 API instead of v2 (default false)

Example:

{
  "name": "get_repositories",
  "arguments": {
    "account": "upbound",
    "filter": "type = 'provider' AND public = true"
  }
}

5. reload_auth

Reload authentication from UP CLI configuration. Useful when switching UP CLI profiles.

Parameters:

• No parameters required

Example:

{
  "name": "reload_auth",
  "arguments": {}
}

6. get_package_version_resources

Get package version resources for a supplied repository name.

Parameters:

• account (string, required): Account/organization name. For example upbound.
• repository_name (string, required): The name of the repository. For example provider-aws-s3.
• version (string, required): The version of the package. For example v1.23.1.

Example:

{
  "name": "get_package_version_resources",
  "arguments": {
    "account": "upbound",
    "repository_name": "provider-aws-s3",
    "version": "v1.23.1"
  }
}

7. get_package_version_composition_resources

Get package version composition resources for a supplied group, kind and version and composition.

Parameters:

• account (string, required): Account/organization name. For example upbound.
• repository_name (string, required): The name of the repository. For example configuration-caas.
• version (string, required): The version of the package. For example v0.4.0.
• resource_group (string, required): The group of the resource. For example caas.upbound.io.
• resource_kind (string, required): The kind of the resource. For example XCluster.
• composition_name (string, required): The kind of the resource. For example xclusters.caas.upbound.io.

Example:

{
  "name": "get_package_version_composition_resources",
  "arguments": {
    "account": "upbound",
    "repository_name": "configuration-caas",
    "version": "v0.4.0",
    "resource_group": "caas.upbound.io",
    "resource_kind": "XCluster",
    "composition_name": "xclusters.caas.upbound.io"
  }
}

8. get_package_version_groupkind_resources

Get package version resources for a supplied group, kind and version.

Parameters:

• account (string, required): Account/organization name. For example upbound.
• repository_name (string, required): The name of the repository. For example provider-aws-s3.
• version (string, required): The version of the package. For example v1.23.1.
• resource_group (string, required): The group of the resource. For example s3.aws.upbound.io.
• resource_kind (string, required): The kind of the resource. For example Bucket.

Example:

{
  "name": "get_package_version_groupkind_resources",
  "arguments": {
    "account": "upbound",
    "repository_name": "provider-aws-s3",
    "version": "v1.23.1",
    "resource_group": "s3.aws.upbound.io",
    "resource_kind": "Bucket"
  }
}

9. get_package_version_examples

Get package version examples for a supplied group, kind and version.

Parameters:

• account (string, required): Account/organization name. For example upbound.
• repository_name (string, required): The name of the repository. For example provider-aws-s3.
• version (string, required): The version of the package. For example v1.23.1.
• resource_group (string, required): The group of the resource. For example s3.aws.upbound.io.
• resource_kind (string, required): The kind of the resource. For example Bucket.

Example:

{
  "name": "get_package_version_examples",
  "arguments": {
    "account": "upbound",
    "repository_name": "provider-aws-s3",
    "version": "v1.23.1",
    "resource_group": "s3.aws.upbound.io",
    "resource_kind": "Bucket"
  }
}

Authentication

The MCP server uses UP CLI authentication for accessing marketplace resources:

Prerequisites

1. Install the UP CLI: https://docs.upbound.io/cli/
2. Authenticate with your Upbound account: up login
3. Ensure your UP CLI config is accessible to the Docker container

Docker Configuration

The server automatically loads authentication from your UP CLI configuration when the container starts. Make sure to mount your UP CLI config directory:

-v ~/.up:/mcp/.up:ro

Switching Profiles

If you have multiple UP CLI profiles, you can:

1. Switch profiles using up profile use <profile-name>
2. Use the reload_auth tool to reload the new authentication without restarting the server

Private Resources

The server will automatically use your authenticated session to access private repositories and resources that your account has permission to view.

API Filtering (v2)

The v2 API supports advanced filtering using AIP-160 format:

Package Search Filters

• query = 'crossplane' - Text search
• family = 'upbound/provider-aws' - Family repository
• packageType = 'provider' - Package type
• accountName = 'upbound' - Account name
• public = true - Public packages only
• tier = 'official' - Official tier packages

Repository Filters

• type = 'provider' - Repository type
• name = 'my-repo' - Repository name
• public = true - Public repositories
• policy = 'publish' - Repository policy
• creation_date > '2023-01-01' - Created after date

Combining Filters

(accountName = 'upbound' OR accountName = 'crossplane') AND public = true AND tier = 'official'

Use Cases

1. Package Discovery

Find packages for specific cloud providers or use cases:

Search for "AWS S3" packages to find providers and configurations for S3 resources.

2. Composition Development

Get examples and CRDs for building compositions:

1. Search for provider packages
2. Get package metadata to see available CRDs
3. Get examples to understand usage patterns
4. Use CRDs and examples to build compositions

3. Package Analysis

Analyze package dependencies and compatibility:

1. Get package metadata for dependency information
2. Check available versions
3. Review documentation and examples

4. Repository Management

Browse and manage organization repositories:

1. Ensure UP CLI is authenticated (up login)
2. List repositories with filtering
3. Get detailed repository information

Configuration

The server automatically detects and loads UP CLI configuration from the
following locations:

1. /mcp/.up/config.json (when running in Docker with mounted config)
2. ~/.up/config.json (default UP CLI location)

No additional configuration is required if UP CLI is properly set up and
authenticated.

As an Addon

Note, the marketplace-mcp-server does still need authentication as described in
the above section. In order to fulfill that need, you should provide a secret
with the contents of the ~/.up/config.json.

For example:

  kubectl -n crossplane-system create secret generic up-config --from-file=config.json=path/to/up/config.json

Development

Prerequisites

• Go 1.23 or later (required by mcp-go framework)
• Docker (for containerization)

Running Locally

Stdio Transport (for MCP clients like Cursor):

# Run the built binary directly
./mcp-server

# Or run with Docker
docker run -i --rm -v ~/.up:/mcp/.up:ro marketplace-mcp-server:latest

HTTP Transport (for web applications and REST clients):

# Run the HTTP server
./mcp-http

# Or run with Docker
docker run --rm -p 8765:8765 -v ~/.up:/mcp/.up:ro marketplace-mcp-server-http:latest

Testing

go test ./...

Architecture

The server is built using the mcp-go framework, which provides:

• JSON-RPC 2.0 Compliance: Full adherence to MCP protocol specifications
• Multiple Transports: Built-in support for stdio, HTTP, and SSE transports
• Type Safety: Strongly typed request/response handling
• Middleware Support: Extensible architecture for authentication and logging
• Error Handling: Robust error handling with proper MCP error codes

Key Components

• Server: Main MCP server using mcp-go framework
• Handlers: Tool handlers for marketplace operations
• Auth Manager: UP CLI authentication integration
• Marketplace Client: HTTP client for Upbound Marketplace API

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Contact the maintainers

Examples

Finding AWS Providers

{
  "name": "search_packages",
  "arguments": {
    "query": "aws",
    "package_type": "provider",
    "tier": "official"
  }
}

Getting Package Documentation

{
  "name": "get_package_assets",
  "arguments": {
    "account": "upbound",
    "repository": "provider-aws",
    "version": "latest",
    "asset_type": "docs"
  }
}

Browsing Organization Repositories

{
  "name": "get_repositories",
  "arguments": {
    "account": "crossplane-contrib",
    "filter": "type = 'configuration' AND public = true"
  }
}