What Is the Role of the `url` Field in a Claude Plugin Manifest?

The url field in a Claude plugin manifest specifies the base HTTPS address where the plugin's HTTP API is hosted, and Claude uses it to construct full request URLs by appending each action's relative path.

The anthropics/claude-plugins-community repository provides canonical examples of how the url property functions as the entry point for all plugin API interactions. This field lives at the top level of every plugin.json or .mcp.json manifest file and directly determines where Claude sends requests when invoking plugin capabilities.

Where the url Field Is Defined

According to the source code in the anthropics/claude-plugins-community repository, the url field appears in multiple manifest locations:

• quickdesign/.claude-plugin/plugin.json — Defines url: "https://quickdesign.io" for the QuickDesign plugin
• tres-finance-plugin/.mcp.json — Contains the base URL for the Tres Finance service
• testdino/.mcp.json — Demonstrates the field in a demo plugin context

These files confirm that the url field is mandatory at the manifest root level and must contain a fully-qualified HTTPS URL.

How Claude Uses the url Field to Route Requests

When Claude needs to execute a plugin action, it performs URL construction by combining two values:

1. The base url from the manifest
2. The relative path from the individual action definition

This concatenation happens automatically for every API call. Consider this example from quickdesign/.claude-plugin/plugin.json:

{
  "name": "quickdesign",
  "description": "Generate visual designs from prompts",
  "url": "https://quickdesign.io",
  "auth": {
    "type": "none"
  },
  "actions": [
    {
      "name": "createDesign",
      "description": "Create a design based on a text prompt",
      "path": "/v1/designs",
      "method": "POST",
      "input_schema": {
        "type": "object",
        "properties": {
          "prompt": { "type": "string", "description": "User's design prompt" }
        },
        "required": ["prompt"]
      }
    }
  ]
}

For the createDesign action above, Claude constructs the request URL as follows:

base_url = "https://quickdesign.io"
endpoint = "/v1/designs"
full_url = f"{base_url}{endpoint}"  # → https://quickdesign.io/v1/designs

The url field thus serves as the canonical entry point for all HTTP traffic between Claude and your plugin service.

Security and Validation Requirements

The url field carries strict security constraints as implemented in the Claude plugin system:

• Protocol requirement — Must use https:// (unencrypted HTTP is rejected)
• Server verification — The endpoint must serve a valid OpenAPI specification
• Authentication compatibility — Must respect the auth configuration (API keys, OAuth tokens, or none)

Environment Flexibility via the url Field

One practical advantage of isolating the base address is deployment portability. You can maintain identical action definitions across environments by only modifying the url value:

Production configuration:

{
  "name": "quickdesign",
  "url": "https://quickdesign.io",
  "actions": [...]
}

Staging configuration:

{
  "name": "quickdesign",
  "url": "https://staging.quickdesign.io",
  "actions": [...]
}

All action paths remain unchanged. This pattern appears throughout anthropics/claude-plugins-community, where the same manifest structure supports multiple deployment scenarios.

Discovery and Marketplace Integration

The url field enables pre-activation verification in the Claude marketplace. As shown in .claude-plugin/marketplace.json, the repository lists plugins with their source URLs to validate reachability before users install them. This discovery mechanism relies on the url field being publicly resolvable and correctly configured.

Summary

• The url field in a Claude plugin manifest defines the base HTTPS address for all API requests
• Claude concatenates this base URL with each action's path to form complete request URLs
• The field enables environment switching without modifying action definitions
• Security validation requires valid HTTPS, proper authentication handling, and OpenAPI specification availability
• The repository anthropics/claude-plugins-community demonstrates these patterns in plugin.json and .mcp.json files across multiple plugins

Frequently Asked Questions

What happens if the url field is missing or invalid?

Claude will reject the plugin manifest during validation. The url field is mandatory at the top level of plugin.json or .mcp.json files, and it must contain a valid HTTPS URL. Invalid values prevent plugin installation and display error messages in the marketplace interface.

Can I use environment variables or dynamic values in the url field?

No. The manifest files in anthropics/claude-plugins-community use static string values only. For environment-specific deployments, maintain separate manifest files with different url values, or use a build process to inject the correct base URL before distribution.

Does the url field support subpaths or must it be a domain root?

The url field can include subpaths. While examples like https://quickdesign.io use domain roots, you could specify https://api.example.com/v2 as your base URL. Claude appends action path values to whatever url you provide, so plan your endpoint structure accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}