# MiniURL MCP Server

Endpoint: https://workers.miniurl.com/mcp

MiniURL provides a remote Model Context Protocol server for agent clients that support Streamable HTTP and JSON-RPC tool calls.

## Preferred Flow

1. For production Agent access, discover the OAuth Protected Resource and Authorization Server metadata, complete OAuth 2.1 + PKCE, and use the short-lived scoped at_ token.
2. Call shorten_url first only for low-risk guest bootstrap when no OAuth grant is available; MiniURL can create a guest token automatically.
3. Call check_alias before creating a link with a custom alias; the create operation remains atomic if another client wins the race.
4. Keep the OAuth at_ token in the MCP client's Authorization header; the server never accepts a long-lived mk_ key through MCP.
5. Use registered tools for link management, analytics, domains, and tags. Send the scoped at_ token on every protected request. Destructive or paid calls return a human approval link when policy requires it.

## CLI Setup

```toml
# ~/.codex/config.toml
[mcp_servers.miniurl]
url = "https://workers.miniurl.com/mcp"
auth = "oauth"
```

Then run codex mcp login miniurl to complete OAuth.

```bash
claude mcp add --transport http miniurl https://workers.miniurl.com/mcp
gemini mcp add --transport http miniurl https://workers.miniurl.com/mcp
```

OpenAI Responses API must register the remote MCP server explicitly:

```js
const response = await openai.responses.create({
  model: "gpt-5",
  input: "Shorten https://example.com/launch with MiniURL.",
  tools: [{
    type: "mcp",
    server_label: "miniurl",
    server_description: "Use MiniURL to create and manage short links.",
    server_url: "https://workers.miniurl.com/mcp",
    allowed_tools: ["shorten_url"],
    require_approval: "always"
  }]
});
```

For registered tools, add a short-lived scoped `authorization` token. A webpage link alone cannot install or authorize an MCP server in an Agent runtime.

## Core Tools

- shorten_url
- check_alias
- create_guest_token
- clear_authentication
- send_registration_code
- verify_registration_code
- get_account_status
- list_links
- get_link
- update_link
- delete_link
- bulk_create_links
- list_domains
- add_domain
- delete_domain
- verify_domain
- get_link_stats
- start_pro_upgrade
- list_tags
- create_tag
- delete_tag
- tag_link
- untag_link

## Raw Streamable HTTP

Preferred protocol `2026-07-28` is stateless: there is no initialize handshake or Session ID. Every request includes matching `MCP-Protocol-Version`, `Mcp-Method`, required `_meta` protocol fields, and `Mcp-Name` for `tools/call`. Call `server/discover`, `tools/list`, or `tools/call` directly. If guest bootstrap returns a `gt_` token, pass it explicitly on later requests.

Legacy protocols through `2025-11-25` remain available with initialize, notifications/initialized, Mcp-Session-Id, and DELETE lifecycle compatibility. Protected tools require `Authorization: Bearer at_xxx` on every request in both modes. Each POST contains one JSON-RPC message; batches are rejected.

OAuth discovery advertises Client ID Metadata Documents and retains Dynamic Client Registration as a fallback.

## Machine Contract

Every tool publishes an outputSchema and readOnlyHint/destructiveHint/idempotentHint/openWorldHint annotations. Tool results use a canonical structuredContent envelope with data, request_id, stable error codes, retryable, optional retry_after, required_scope, user_action_required, and next_actions. shorten_url, update_link, delete_link, bulk_create_links, and start_pro_upgrade accept an ASCII idempotency_key; list_links prefers cursor pagination. Agent create/update redirect tools support dry_run previews, while link/tag deletion, domain changes, and billing require human approval by default.

## REST Fallback

When MCP is not available, use the REST API at https://workers.miniurl.com/api/v1 and the OpenAPI spec at https://miniurl.com/openapi.json.