AI agents

Three ways in#

• MCP server (recommended) for Claude Desktop, Claude Code, Cursor, VS Code and any other MCP client. See MCP server.
• OpenAPI for function-calling frameworks: OpenAI GPT Actions and Assistants, LangChain, LlamaIndex, Semantic Kernel and others. See OpenAPI.
• REST with plain HTTP, as described in the API reference.

There is also a machine-readable index for LLMs at https://furl.io/llms.txt.

Step 1: create an API key for the agent#

1. Open API keys

   In the dashboard, go to Settings → API keys and press Create. Your email must be verified.

2. Name it after the agent

   For example claude-desktop.

3. Copy the key

   The key starts with furl_, is 45 characters long and is shown only once.

MCP server#

Tools#

Errors come back as tool errors with a code and a message, for example plan_limit_reached, custom_code_limit, link_expiry_not_in_plan, code_blocked, code_taken, validation_error, not_found or too_many_concurrent_requests.

Claude Code#

claude mcp add --transport http furl https://furl.io/mcp --header "Authorization: Bearer furl_YOUR_KEY"

Claude Desktop#

Open Settings → Developer → Edit config and add furl.io to claude_desktop_config.json. This uses the mcp-remote bridge.

{
  "mcpServers": {
    "furl": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://furl.io/mcp", "--header", "Authorization: Bearer ${FURL_API_KEY}"],
      "env": { "FURL_API_KEY": "furl_YOUR_KEY" }
    }
  }
}

Cursor#

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

{
  "mcpServers": {
    "furl": {
      "url": "https://furl.io/mcp",
      "headers": { "Authorization": "Bearer furl_YOUR_KEY" }
    }
  }
}

VS Code#

Add this to .vscode/mcp.json. VS Code asks for the key the first time and stores it as a secret.

{
  "servers": {
    "furl": {
      "type": "http",
      "url": "https://furl.io/mcp",
      "headers": { "Authorization": "Bearer ${input:furl-key}" }
    }
  },
  "inputs": [{ "type": "promptString", "id": "furl-key", "description": "furl.io API key", "password": true }]
}

Any client: test with curl#

The server speaks plain JSON-RPC, so you can call a tool directly:

curl -s https://furl.io/mcp \
  -H "Authorization: Bearer furl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"shorten_url","arguments":{"url":"https://example.com/launch","max_views":100}}}'

Example prompts#

• “Shorten https://example.com/spring-sale and make it expire after 500 views.”
• “How many clicks did furl.io/launch get this week, and from which countries?”
• “Pause my link AgentDemo.”

OpenAPI (function calling)#

The spec is at https://furl.io/api/v1/openapi.json (OpenAPI 3.0.3, CORS-enabled). Import it into OpenAI GPT Actions (Authentication: API key, Auth type: Bearer), LangChain’s OpenAPI toolkit, LlamaIndex, Semantic Kernel or Postman.

Expose only the operations the agent needs, for example createLink, getLink, listLinks and getLinkStats. Operation IDs are stable.

import os, requests
r = requests.post("https://furl.io/api/v1/links",
    headers={"Authorization": f"Bearer {os.environ['FURL_API_KEY']}"},
    json={"original_url": "https://example.com/launch", "max_clicks": 100},
    timeout=10)
r.raise_for_status()
print(r.json()["short_url"])

llms.txt#

https://furl.io/llms.txt is a concise Markdown summary of furl.io for LLMs: what it does, how to authenticate, the MCP endpoint, the main REST calls and links to these docs. Point an agent at it, or paste it into a system prompt.

Limits#