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

> Discover the role of the url field in a Claude plugin manifest. Learn how it specifies the base API address for Claude to construct request URLs.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: api-reference
- Published: 2026-09-01

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) or [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json)** — Defines `url: "https://quickdesign.io"` for the QuickDesign plugin
- **[`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json)** — Contains the base URL for the Tres Finance service
- **[`testdino/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json):

```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:

```python
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:**

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

```

**Staging configuration:**

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) or [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.