> ## Documentation Index
> Fetch the complete documentation index at: https://docs.h0p.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect H0p to AI development tools with the Model Context Protocol

The Model Context Protocol (MCP) enables AI assistants and development tools to interact directly with H0p. Create and manage short links, domains, and view analytics without leaving your AI workflow.

## What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI tools to securely connect to external services. With H0p's MCP server, your AI assistant can:

<CardGroup cols={2}>
  <Card title="Create links" icon="link">
    Generate short links directly from conversations or code comments.
  </Card>

  <Card title="Manage domains" icon="globe">
    View and configure custom domains without opening the dashboard.
  </Card>

  <Card title="View analytics" icon="chart-line">
    Get click stats and performance data in your development workflow.
  </Card>

  <Card title="Organize content" icon="folder">
    Create and manage folders and tags programmatically.
  </Card>
</CardGroup>

## Supported tools

H0p's MCP server works with:

| Tool                              | Type        | Status             |
| --------------------------------- | ----------- | ------------------ |
| [Claude Desktop](#claude-desktop) | Desktop app | Supported          |
| [Claude Code](#claude-code)       | CLI         | Supported          |
| [Cursor](#cursor)                 | IDE         | Supported          |
| [Windsurf](#windsurf)             | IDE         | Supported          |
| [ChatGPT](#chatgpt)               | Web app     | Via custom actions |

## Prerequisites

Before setting up MCP, you need:

1. **H0p account** - Sign up at [dashboard.h0p.co](https://dashboard.h0p.co)
2. **Organization slug** - Found in your organization settings

Your MCP URL follows this pattern:

```
https://api.h0p.co/mcp/{organization-slug}
```

<Note>
  H0p's MCP server uses OAuth 2.0 authentication. You'll be prompted to authorize access when connecting for the first time.
</Note>

## Claude Desktop

Claude Desktop supports remote MCP servers with OAuth authentication.

<Steps>
  <Step title="Open Connectors settings">
    Open Claude Desktop and go to **Settings** > **Connectors**.
  </Step>

  <Step title="Add custom connector">
    Click **Add custom connector** at the bottom of the Connectors section.
  </Step>

  <Step title="Enter the MCP URL">
    Enter your H0p MCP server URL:

    ```
    https://api.h0p.co/mcp/{your-org-slug}
    ```

    Click **Add** to proceed.
  </Step>

  <Step title="Authenticate with OAuth">
    Claude Desktop will redirect you to H0p's authorization page. Sign in with your H0p account and authorize the connection.

    Once authorized, Claude will have access to your H0p tools.
  </Step>

  <Step title="Configure tool permissions">
    Back in **Settings** > **Connectors**, click on H0p to configure which tools Claude can use. Enable or disable specific tools based on your needs.
  </Step>
</Steps>

### Example usage

Once connected, ask Claude:

> "Create a short link to [https://example.com/landing](https://example.com/landing) with the slug 'promo'"

> "Show me the click stats for the last 7 days"

> "List all my custom domains"

## Claude Code

Claude Code supports OAuth 2.0 authentication for remote MCP servers.

<Steps>
  <Step title="Add the MCP server">
    Use the CLI to add H0p as a remote HTTP server:

    ```bash theme={null}
    claude mcp add --transport http h0p https://api.h0p.co/mcp/{your-org-slug}
    ```
  </Step>

  <Step title="Authenticate with OAuth">
    In Claude Code, use the `/mcp` command to authenticate:

    ```
    > /mcp
    ```

    Select **Authenticate** for H0p. This opens your browser for OAuth authorization.
  </Step>

  <Step title="Start using">
    After authentication, Claude Code has access to H0p tools. Authentication tokens are stored securely and refreshed automatically.
  </Step>
</Steps>

<Tip>
  Use `/mcp` anytime to check connection status, re-authenticate, or clear authentication.
</Tip>

See the [Claude Code integration guide](/ai-tools/claude-code) for detailed setup instructions.

## Cursor

Cursor supports MCP servers with OAuth authentication.

<Steps>
  <Step title="Open Cursor settings">
    Go to **Settings** > **Features** > **MCP Servers**.
  </Step>

  <Step title="Add H0p server">
    Add a new MCP server with the HTTP transport:

    ```json theme={null}
    {
      "h0p": {
        "type": "http",
        "url": "https://api.h0p.co/mcp/{your-org-slug}"
      }
    }
    ```
  </Step>

  <Step title="Authenticate">
    When Cursor attempts to connect, you'll be prompted to authorize via OAuth. Complete the authorization in your browser.
  </Step>

  <Step title="Reload Cursor">
    Restart Cursor or reload the window to apply changes.
  </Step>
</Steps>

See the [Cursor integration guide](/ai-tools/cursor) for detailed setup instructions.

## Windsurf

Windsurf supports remote MCP servers with OAuth.

<Steps>
  <Step title="Open Windsurf settings">
    Navigate to **Settings** > **AI** > **MCP Configuration**.
  </Step>

  <Step title="Add H0p server">
    Configure the H0p MCP server:

    ```json theme={null}
    {
      "servers": {
        "h0p": {
          "type": "http",
          "url": "https://api.h0p.co/mcp/{your-org-slug}"
        }
      }
    }
    ```
  </Step>

  <Step title="Authenticate">
    Complete OAuth authorization when prompted.
  </Step>
</Steps>

See the [Windsurf integration guide](/ai-tools/windsurf) for detailed setup instructions.

## ChatGPT

ChatGPT supports MCP servers with OAuth authentication via Developer Mode. This feature is available for **Pro, Plus, Business, Enterprise, and Education** accounts.

<Tabs>
  <Tab title="MCP with OAuth (recommended)">
    Use Developer Mode to connect H0p with OAuth authentication:

    <Steps>
      <Step title="Enable Developer Mode">
        In ChatGPT, go to **Settings** > **Connectors** > **Advanced** and enable **Developer Mode**.

        <Warning>
          Developer Mode is powerful but requires caution. Test connectors thoroughly and confirm all data-modifying actions before execution.
        </Warning>
      </Step>

      <Step title="Add H0p MCP server">
        Click **Add Connector** and enter your H0p MCP URL:

        ```
        https://api.h0p.co/mcp/{your-org-slug}
        ```
      </Step>

      <Step title="Authenticate with OAuth">
        ChatGPT will redirect you to H0p's authorization page. Sign in and authorize the connection.
      </Step>

      <Step title="Start using">
        Once connected, ChatGPT has access to all H0p MCP tools.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Custom GPT with API key">
    Alternatively, create a custom GPT using API key authentication:

    <Steps>
      <Step title="Create an API key">
        In H0p, go to **Developer Tools** > **API Keys** and create a new key.
      </Step>

      <Step title="Create a custom GPT">
        Go to **Explore** > **Create a GPT** in ChatGPT.
      </Step>

      <Step title="Configure actions">
        In the **Actions** section, add:

        * **OpenAPI schema URL**: `https://api.h0p.co/doc`
        * **Authentication**: API key in header
        * **Header name**: `x-api-key`
        * **API key**: Your H0p API key
      </Step>

      <Step title="Set instructions">
        Add instructions for how the GPT should use H0p:

        ```
        You have access to H0p for URL shortening. Use it when users want to:
        - Create short links
        - View link analytics
        - Manage their domains
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Available MCP tools

H0p's MCP server provides these tools:

### Short links

| Tool                | Description             |
| ------------------- | ----------------------- |
| `create-short-link` | Create a new short link |
| `update-short-link` | Update an existing link |
| `get-short-link`    | Get link details        |
| `list-short-links`  | List all short links    |
| `delete-short-link` | Delete a link           |

### Domains

| Tool               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `create-domain`    | Add a new custom domain                                |
| `update-domain`    | Update domain settings                                 |
| `get-domain`       | Get domain details                                     |
| `list-domains`     | List all domains                                       |
| `get-all-domains`  | List all available domains including platform defaults |
| `check-domain-dns` | Verify domain DNS configuration                        |
| `delete-domain`    | Remove a domain                                        |

### Folders

| Tool            | Description                 |
| --------------- | --------------------------- |
| `create-folder` | Create a new folder         |
| `update-folder` | Update folder name or color |
| `get-folder`    | Get folder details          |
| `list-folders`  | List all folders            |
| `delete-folder` | Delete a folder             |

### Tags

| Tool         | Description              |
| ------------ | ------------------------ |
| `create-tag` | Create a new tag         |
| `update-tag` | Update tag name or color |
| `get-tag`    | Get tag details          |
| `list-tags`  | List all tags            |
| `delete-tag` | Delete a tag             |

### Analytics

| Tool                   | Description                        |
| ---------------------- | ---------------------------------- |
| `get-stats-overview`   | Get analytics grouped by dimension |
| `get-clicks-over-time` | Get daily click counts             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth authorization failed">
    If authorization fails:

    * Ensure you're logged into the correct H0p account
    * Check that your organization slug in the URL is correct
    * Try clearing your browser cookies and re-authorizing
    * Verify your H0p account has access to the specified organization
  </Accordion>

  <Accordion title="Connection failed">
    Verify your MCP URL:

    * URL should be `https://api.h0p.co/mcp/{org-slug}`
    * Organization slug must match your active organization
    * Check your internet connection
  </Accordion>

  <Accordion title="Tools not showing">
    MCP tools may take a moment to load. Try:

    * Refreshing the connection
    * Restarting your AI tool
    * Re-authenticating via `/mcp` (Claude Code) or Connectors settings
  </Accordion>

  <Accordion title="Permission denied errors">
    Your H0p account role determines available permissions:

    * Owners and Admins have full access
    * Members have limited access to some features
    * Check your role in organization settings
  </Accordion>

  <Accordion title="Rate limiting">
    MCP requests count against API rate limits. If you hit limits:

    * Wait a few seconds between requests
    * Consider batching operations
  </Accordion>
</AccordionGroup>

***

## Documentation MCP

In addition to the H0p MCP server for managing links, this documentation site also provides an MCP server for AI-assisted documentation browsing.

### What it does

The documentation MCP allows AI tools to search and navigate H0p's documentation. When connected, AI assistants can:

* Search documentation content
* Find relevant pages for specific questions
* Navigate to the right documentation section

### Connecting to the documentation MCP

Look for the MCP button on any documentation page to copy the configuration for your AI tool. This is separate from the main H0p MCP server and is specifically for browsing documentation.

### Example queries

With the documentation MCP configured, you can ask your AI assistant:

> "How do I create a webhook in H0p?"

> "What are the rate limits for the H0p API?"

> "Show me how to set up a custom domain"

The AI will search this documentation and provide relevant answers with links to the source pages.

### Code generation

You can also ask your AI assistant to generate code that integrates with the H0p API. For example:

> "Write a Go function that creates a short link with UTM parameters from a struct containing campaign data"

> "Create a Python script that fetches all my short links and exports them to a CSV file"

> "Build a TypeScript utility that batch-creates short links from an array of URLs"

The AI will use the documentation to understand the H0p API structure and generate accurate, working code:

```go theme={null}
// Example output for the Go request
func CreateCampaignLink(client *http.Client, apiKey string, campaign Campaign) (*ShortLink, error) {
    payload := map[string]interface{}{
        "destination": map[string]string{
            "type":  "link",
            "value": campaign.URL,
        },
        "slug": campaign.Slug,
        "utmSource":   campaign.Source,
        "utmMedium":   campaign.Medium,
        "utmCampaign": campaign.Name,
    }

    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.h0p.co/short-link", bytes.NewBuffer(body))
    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := client.Do(req)
    // ... handle response
}
```

## Best practices

<AccordionGroup>
  <Accordion title="Use descriptive prompts">
    Be specific about what you want:

    **Good**: "Create a short link to [https://example.com/sale](https://example.com/sale) with slug 'spring-sale' and tag it with 'marketing'"

    **Less specific**: "Make a link"
  </Accordion>

  <Accordion title="Batch operations">
    When creating multiple links, ask for them all at once to reduce API calls.
  </Accordion>

  <Accordion title="Review before committing">
    When using MCP with code generation, review the generated API calls before running them in production.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/platform/webhooks">
    Set up real-time notifications.
  </Card>
</CardGroup>