Integration Guide

MCP Client Setup

Add the URL Shortener MCP server to your MCP client configuration:

{
  "mcpServers": {
    "url-shortener": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "https://apistack.online/api/mcp/utilities/url-shortener-utilities/sse",
        "-H", "Content-Type: application/json",
        "-H", "Authorization: Bearer YOUR_API_KEY",
        "--data-raw", "@-"
      ],
      "transport": "sse"
    }
  }
}

Authentication

Ensure your API key has PRO or ENTERPRISE plan access:

export MCP_URL_SHORTENER_API_KEY="your-api-key"

Usage Examples

Basic URL Shortening

const result = await mcpClient.callTool('shorten_url', {
  url: 'https://docs.microsoft.com/en-us/azure/app-service/overview'
});

URL Expansion

const result = await mcpClient.callTool('expand_url', {
  url: 'https://tinyurl.com/ygpfwsyv'
});

# URL Shortener/Expander MCP Server

## Overview

The URL Shortener/Expander MCP server provides comprehensive URL shortening and expanding functionality through the Model Context Protocol (MCP). This server provides comprehensive functionality.

## 🔧 Exposed Tools

This MCP server exposes **3 tools** for AI agents:

### 1. `shorten_url`
**Purpose**: Shorten long URLs using TinyURL service
- **Input**: 
  - `url` (string, required) - The long URL to shorten
  - `alias` (string, optional) - Custom alias for the shortened URL
  - `includeMetadata` (boolean, optional) - Include additional metadata in response
- **Output**: Shortened URL with metadata
- **Example**: "https://docs.microsoft.com/en-us/azure/app-service/overview" → "https://tinyurl.com/ygpfwsyv"

### 2. `expand_url`
**Purpose**: Expand shortened URLs to get the original URL
- **Input**: 
  - `url` (string, required) - The shortened URL to expand
  - `includeMetadata` (boolean, optional) - Include additional metadata in response
- **Output**: Original URL with metadata
- **Example**: "https://tinyurl.com/osh3vqo" → "https://github.com/microsoft/vscode"

### 3. `get_url_info`
**Purpose**: Get information about URL shortening and expanding
- **Input**: `infoType` (enum: "overview", "examples", "services")
- **Output**: Educational information about URL shortening
- **Use case**: Help AI agents understand URL shortening services and best practices

## 🔗 Server Details

- **Category**: Utilities
- **Transport**: Server-Sent Events (SSE)
- **Endpoint**: `/api/mcp/utilities/url-shortener/sse`
- **Authentication**: Required (PRO/ENTERPRISE plans only)
- **Wrapped API**: `/api/utilities/url-shortener/v1`
- **Rate Limits**: 100 requests/minute, 2000 requests/hour

## 📋 Prerequisites

- **Subscription**: PRO or ENTERPRISE plan
- **API Key**: Valid API key with URL Shortener access
- **MCP Client**: Any MCP-compatible client or AI agent

## 🚀 Quick Start

### Connection Setup
```
Endpoint: https://apistack.online/api/mcp/utilities/url-shortener/sse
Method: POST
Headers:
  Content-Type: application/json
  Authorization: Bearer YOUR_API_KEY
```

### Basic MCP Requests

#### List Available Tools
```json
{
  "jsonrpc": "2.0",
  "id": "list-tools",
  "method": "tools/list"
}
```

#### Shorten a Long URL
```json
{
  "jsonrpc": "2.0",
  "id": "shorten-1",
  "method": "tools/call",
  "params": {
    "name": "shorten_url",
    "arguments": {
      "url": "https://docs.microsoft.com/en-us/azure/app-service/overview",
      "includeMetadata": true
    }
  }
}
```

#### Shorten with Custom Alias
```json
{
  "jsonrpc": "2.0",
  "id": "shorten-2",
  "method": "tools/call",
  "params": {
    "name": "shorten_url",
    "arguments": {
      "url": "https://github.com/microsoft/vscode",
      "alias": "vscode-repo",
      "includeMetadata": true
    }
  }
}
```

#### Expand a Shortened URL
```json
{
  "jsonrpc": "2.0",
  "id": "expand-1",
  "method": "tools/call",
  "params": {
    "name": "expand_url",
    "arguments": {
      "url": "https://tinyurl.com/osh3vqo",
      "includeMetadata": true
    }
  }
}
```

## 💻 Implementation Examples

### Python Example
```python
import requests
import json

class UrlShortenerMCPClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}"
        }
        self.endpoint = f"{base_url}/api/mcp/utilities/url-shortener/sse"
    
    def shorten_url(self, url, alias=None, include_metadata=False):
        arguments = {
            "url": url,
            "includeMetadata": include_metadata
        }
        if alias:
            arguments["alias"] = alias
            
        request = {
            "jsonrpc": "2.0",
            "id": "shorten",
            "method": "tools/call",
            "params": {
                "name": "shorten_url",
                "arguments": arguments
            }
        }
        
        response = requests.post(self.endpoint, headers=self.headers, json=request)
        result = response.json()
        return result["result"]
    
    def expand_url(self, url, include_metadata=False):
        request = {
            "jsonrpc": "2.0",
            "id": "expand",
            "method": "tools/call",
            "params": {
                "name": "expand_url",
                "arguments": {
                    "url": url,
                    "includeMetadata": include_metadata
                }
            }
        }
        
        response = requests.post(self.endpoint, headers=self.headers, json=request)
        result = response.json()
        return result["result"]
    
    def get_url_info(self, info_type):
        request = {
            "jsonrpc": "2.0",
            "id": "info",
            "method": "tools/call",
            "params": {
                "name": "get_url_info",
                "arguments": {
                    "infoType": info_type
                }
            }
        }
        
        response = requests.post(self.endpoint, headers=self.headers, json=request)
        result = response.json()
        return result["result"]

# Usage
client = UrlShortenerMCPClient("https://apistack.online", "YOUR_API_KEY")

# Shorten a URL
short_result = client.shorten_url(
    "https://docs.microsoft.com/en-us/azure/app-service/overview", 
    alias="azure-docs",
    include_metadata=True
)
print(f"Shortened URL: {short_result['shortUrl']}")

# Expand the URL
expand_result = client.expand_url(short_result['shortUrl'], include_metadata=True)
print(f"Expanded URL: {expand_result['expandedUrl']}")

# Get information about URL shortening
info_result = client.get_url_info("overview")
print(f"URL Shortening Overview: {info_result['content']['title']}")
```

### JavaScript/Node.js Example
```javascript
const axios = require('axios');

class UrlShortenerMCPClient {
    constructor(baseUrl, apiKey) {
        this.baseUrl = baseUrl;
        this.endpoint = `${baseUrl}/api/mcp/utilities/url-shortener/sse`;
        this.headers = {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`
        };
    }

    async shortenUrl(url, alias = null, includeMetadata = false) {
        const arguments = { url, includeMetadata };
        if (alias) arguments.alias = alias;

        const request = {
            jsonrpc: "2.0",
            id: "shorten",
            method: "tools/call",
            params: {
                name: "shorten_url",
                arguments
            }
        };

        const response = await axios.post(this.endpoint, request, { headers: this.headers });
        return response.data.result;
    }

    async expandUrl(url, includeMetadata = false) {
        const request = {
            jsonrpc: "2.0",
            id: "expand",
            method: "tools/call",
            params: {
                name: "expand_url",
                arguments: { url, includeMetadata }
            }
        };

        const response = await axios.post(this.endpoint, request, { headers: this.headers });
        return response.data.result;
    }

    async getUrlInfo(infoType) {
        const request = {
            jsonrpc: "2.0",
            id: "info",
            method: "tools/call",
            params: {
                name: "get_url_info",
                arguments: { infoType }
            }
        };

        const response = await axios.post(this.endpoint, request, { headers: this.headers });
        return response.data.result;
    }
}

// Usage
(async () => {
    const client = new UrlShortenerMCPClient("https://apistack.online", "YOUR_API_KEY");
    
    // Shorten a URL with custom alias
    const shortResult = await client.shortenUrl(
        "https://docs.microsoft.com/en-us/azure/app-service/overview",
        "azure-docs",
        true
    );
    console.log(`Shortened URL: ${shortResult.shortUrl}`);
    
    // Expand the shortened URL
    const expandResult = await client.expandUrl(shortResult.shortUrl, true);
    console.log(`Expanded URL: ${expandResult.expandedUrl}`);
    
    // Get examples about URL shortening
    const examples = await client.getUrlInfo("examples");
    console.log(`URL Examples: ${examples.content.title}`);
})();
```

### cURL Examples
```bash
# List available tools
curl -X POST "https://apistack.online/api/mcp/utilities/url-shortener/sse" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "list-tools",
    "method": "tools/list"
  }'

# Shorten a URL
curl -X POST "https://apistack.online/api/mcp/utilities/url-shortener/sse" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "shorten",
    "method": "tools/call",
    "params": {
      "name": "shorten_url",
      "arguments": {
        "url": "https://docs.microsoft.com/en-us/azure/app-service/overview",
        "alias": "azure-docs",
        "includeMetadata": true
      }
    }
  }'

# Expand a URL
curl -X POST "https://apistack.online/api/mcp/utilities/url-shortener/sse" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "expand",
    "method": "tools/call",
    "params": {
      "name": "expand_url",
      "arguments": {
        "url": "https://tinyurl.com/ygpfwsyv",
        "includeMetadata": true
      }
    }
  }'
```

## 🔒 Security & Authentication

- **Authentication Required**: All requests must include a valid Bearer token
- **Plan Access**: Available on all plans (FREE, PRO, ENTERPRISE)
- **Rate Limiting**: 100 requests/minute, 2000 requests/hour
- **Input Validation**: All URLs are validated for format and security
- **Error Handling**: Comprehensive error responses following MCP protocol

## 📊 Response Format

All tool responses follow the MCP protocol format:

### Success Response (Shorten URL)
```json
{
  "jsonrpc": "2.0",
  "id": "shorten",
  "result": {
    "success": true,
    "operation": "shorten",
    "originalUrl": "https://docs.microsoft.com/en-us/azure/app-service/overview",
    "shortUrl": "https://tinyurl.com/ygpfwsyv",
    "alias": "azure-docs",
    "provider": "tinyurl",
    "metadata": {
      "timestamp": "2025-09-04T12:00:00.000Z",
      "compressionRatio": "85.2%",
      "lengthSaved": 45
    },
    "processedAt": "2025-09-04T12:00:00.000Z"
  }
}
```

### Success Response (Expand URL)
```json
{
  "jsonrpc": "2.0",
  "id": "expand",
  "result": {
    "success": true,
    "operation": "expand",
    "shortUrl": "https://tinyurl.com/osh3vqo",
    "expandedUrl": "https://github.com/microsoft/vscode",
    "redirectType": "http_redirect",
    "statusCode": 301,
    "metadata": {
      "timestamp": "2025-09-04T12:00:00.000Z",
      "redirectsFollowed": 1
    },
    "processedAt": "2025-09-04T12:00:00.000Z"
  }
}
```

### Error Response
```json
{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32603,
    "message": "Invalid URL format"
  }
}
```

## 🧪 Testing

You can test the MCP server using the provided cURL examples above or create a simple test script.

## 🏗️ Architecture

```
AI Agent/Client
       ↓
MCP Protocol (JSON-RPC 2.0)
       ↓
URL Shortener MCP Server (/api/mcp/utilities/url-shortener/sse)
       ↓
Authentication & Validation
       ↓
URL Shortener API (/api/utilities/url-shortener/v1)
       ↓
TinyURL Service Integration
       ↓
Response via MCP Protocol
```

## 📝 Tool Schemas

### shorten_url Schema
```json
{
  "name": "shorten_url",
  "description": "Shorten a long URL using TinyURL service",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "The long URL to shorten"
      },
      "alias": {
        "type": "string",
        "description": "Optional custom alias for the shortened URL"
      },
      "includeMetadata": {
        "type": "boolean",
        "description": "Include additional metadata in the response",
        "default": false
      }
    },
    "required": ["url"]
  }
}
```

### expand_url Schema
```json
{
  "name": "expand_url",
  "description": "Expand a shortened URL to get the original URL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "The shortened URL to expand"
      },
      "includeMetadata": {
        "type": "boolean",
        "description": "Include additional metadata in the response",
        "default": false
      }
    },
    "required": ["url"]
  }
}
```

### get_url_info Schema
```json
{
  "name": "get_url_info",
  "description": "Get information about URL shortening and expanding",
  "inputSchema": {
    "type": "object",
    "properties": {
      "infoType": {
        "type": "string",
        "enum": ["overview", "examples", "services"],
        "description": "Type of URL information to retrieve"
      }
    },
    "required": ["infoType"]
  }
}
```

## 🎯 Use Cases

### Social Media Marketing
- Shorten URLs for Twitter posts with character limits
- Create branded links for Instagram bio
- Track campaign performance with custom aliases

### Email Campaigns
- Clean, professional links in newsletters
- Custom aliases for tracking different email segments
- Reduced risk of link breaking in email clients

### QR Code Generation
- Short URLs work better with QR code generators
- Easier to scan and less prone to errors
- Custom aliases for branded QR campaigns

### SMS Marketing
- Fit long URLs within SMS character limits
- Professional appearance in text messages
- Track click-through rates from SMS campaigns

### Link Management
- Expand suspicious short links before clicking
- Verify redirect destinations for security
- Manage and organize marketing links

## 🤝 Support

For issues, feature requests, or integration help:
- Check the API documentation
- Review the examples above
- Test with the provided cURL commands
- Contact support for assistance

---

**Note**: This MCP server requires a PRO or ENTERPRISE subscription and valid API authentication. The server integrates with TinyURL service for reliable URL shortening and expanding capabilities.

Available Tools

shorten_url

Shorten long URLs using TinyURL service.

Input Parameters:

• url (string, required) - The long URL to shorten
• alias (string, optional) - Custom alias for the shortened URL
• includeMetadata (boolean, optional) - Include additional metadata

Example:

{
  "url": "https://docs.microsoft.com/en-us/azure/app-service/overview",
  "alias": "azure-docs",
  "includeMetadata": true
}

expand_url

Expand shortened URLs to get the original URL.

Input Parameters:

• url (string, required) - The shortened URL to expand
• includeMetadata (boolean, optional) - Include additional metadata

Example:

{
  "url": "https://tinyurl.com/osh3vqo",
  "includeMetadata": true
}

get_url_info

Get information about URL shortening services.

Input Parameters:

• infoType (string, required) - Type of information: "overview", "examples", or "services"

Example:

{
  "infoType": "examples"
}