🤖 AI Integration (MCP)

⚡ Quick Setup

For Claude Code (Recommended)

Claude Code supports HTTP MCP servers directly via CLI. Simply run:

claude mcp add --transport http zip1 https://zip1.io/mcp

Verify installation:

claude mcp list

For Claude Desktop

Option 1: Using mcp-client-cli (Recommended)

Install the MCP client CLI tool to bridge stdio to HTTP:

npm install -g @modelcontextprotocol/client-cli

Then edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "zip1": {
      "command": "mcp-client",
      "args": ["https://zip1.io/mcp"]
    }
  }
}

Restart Claude Desktop and the zip1.io tools will be available.

Option 2: Custom Node.js Proxy

For advanced users, create a custom stdio-to-HTTP bridge script:

#!/usr/bin/env node
const https = require('https');
const readline = require('readline');

const MCP_URL = 'https://zip1.io/mcp';

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  terminal: false
});

rl.on('line', (line) => {
  const request = JSON.parse(line);

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    }
  };

  const req = https.request(MCP_URL, options, (res) => {
    let data = '';
    res.on('data', (chunk) => data += chunk);
    res.on('end', () => {
      console.log(data);
    });
  });

  req.on('error', (error) => {
    console.error(JSON.stringify({
      jsonrpc: '2.0',
      id: request.id,
      error: { code: -32000, message: error.message }
    }));
  });

  req.write(JSON.stringify(request));
  req.end();
});

Make it executable and add to your Claude Desktop config:

chmod +x zip1-mcp-proxy.js

{
  "mcpServers": {
    "zip1": {
      "command": "node",
      "args": ["/path/to/zip1-mcp-proxy.js"]
    }
  }
}

⚙️ Server Configuration

The zip1.io MCP server is available as an HTTP endpoint that any MCP-compatible client can connect to.

Server Details

Using with Other MCP Clients

Any MCP-compatible client that supports HTTP transport can connect to zip1.io. Here are some examples:

Direct HTTP Requests (curl)

curl -X POST https://zip1.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

curl -X POST https://zip1.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_short_url",
      "arguments": {
        "url": "https://example.com",
        "alias": "my-link"
      }
    }
  }'

Python Client Example

import requests

MCP_URL = "https://zip1.io/mcp"

def call_mcp_tool(tool_name, arguments):
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": arguments
        }
    }

    response = requests.post(MCP_URL, json=payload)
    return response.json()

# Example usage
result = call_mcp_tool("create_short_url", {
    "url": "https://example.com",
    "alias": "mcp-docs"
})

print(result)

Self-Hosted Configuration

If you're running your own instance of zip1.io, configure clients to point to your instance:

claude mcp add --transport http zip1 https://your-domain.com/mcp

{
  "mcpServers": {
    "zip1-local": {
      "command": "mcp-client",
      "args": ["http://localhost:8000/mcp"]
    }
  }
}

💬 Example Conversations

Here are some natural language prompts you can use with Claude:

"Shorten https://example.com for me"

"Create a short URL for https://example.com with alias 'docs' and password 'Preview@2026'"

"Show me the stats for short code 'docs', password 'Preview@2026'"

"Can I shorten ftp://myserver.com/file.zip?"

🛠️ Available Tools

The zip1.io MCP server provides four tools that Claude can use:

description on create_short_url is an optional private note for your own integration, up to 100 characters. It is not shown on the link's public pages. Keep it free of personal data you wouldn't want stored. The create response returns it.

🔧 Technical Details

MCP Endpoint

Returns server information, available tools, and configuration details.

Protocol Information

• Protocol Version: MCP 2024-11-05
• Transport: Streamable HTTP
• Message Format: JSON-RPC 2.0
• Rate Limit: 30 requests per minute per IP

Security

• All communication uses HTTPS encryption
• Passwords are hashed with bcrypt before storage
• get_url_stats does not return a password-protected link's destination or statistics until the password argument matches
• Rate limiting prevents abuse
• Same security infrastructure as the REST API

💡 Use Cases

🔍 Troubleshooting

Rate limiting errors?

• The MCP endpoint has a limit of 30 requests per minute
• Wait a minute and try again

Tools not appearing in Claude Code?

• Ensure the MCP server URL is accessible
• Try visiting https://zip1.io/mcp in your browser
• Verify your MCP configuration with claude mcp list

📚 Resources & Documentation

• Official MCP Documentation - Learn more about the Model Context Protocol
• MCP Python SDK - Build your own MCP servers
• REST API Documentation - Traditional API access