Connecting to the MCP Server

This page covers MCP client setup for different environments.

Claude Desktop

Add an entry to claude_desktop_config.json:

{
  "mcpServers": {
    "lnkify": {
      "type": "http",
      "url": "https://mcp.lnkify.io/",
      "headers": {
        "x-api-key": "lf_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop will manage the session lifecycle automatically.

VS Code / Cursor

Configure the MCP server in your IDE settings. Use the same URL and header scheme:

{
  "mcpServers": {
    "lnkify": {
      "url": "https://mcp.lnkify.io/",
      "headers": {
        "x-api-key": "lf_live_YOUR_KEY"
      }
    }
  }
}

Custom Clients (Streamable HTTP)

lnkify speaks JSON-RPC 2.0 over Streamable HTTP. Every client follows the same lifecycle:

Initialize Handshake

Send an initialize request to open a session:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  },
  "id": 1
}

The server responds with a Mcp-Session-Id HTTP header. Save this value — you must send it with every subsequent request.

Session Lifecycle

1. Create — send initialize to get a session ID.
2. Use — include Mcp-Session-Id in every POST request.
3. Discover — call tools/list to enumerate available tools.
4. Call — call tools/call to invoke a tool.
5. Close — send DELETE to the root URL with the session header.

Listing Tools

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}

Returns the full tool catalog with schemas.

Calling a Tool

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_lnkify",
    "arguments": {
      "target": "https://example.com",
      "slug": "my-link"
    }
  },
  "id": 3
}

Session Timeout

Sessions expire after a period of inactivity. If your session expires, re-initialize to get a new one.

Using curl For Testing

# 1. Initialize (save the Mcp-Session-Id header)
curl -v -X POST https://mcp.lnkify.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: lf_live_YOUR_KEY" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

# 2. List tools (replace SESSION_ID)
curl -X POST https://mcp.lnkify.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: lf_live_YOUR_KEY" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

# 3. Call a tool
curl -X POST https://mcp.lnkify.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: lf_live_YOUR_KEY" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"whoami","arguments":{}},"id":3}'

# 4. Close the session
curl -X DELETE https://mcp.lnkify.io/ \
  -H "x-api-key: lf_live_YOUR_KEY" \
  -H "Mcp-Session-Id: SESSION_ID"

Caddy Routing

The mcp.lnkify.io subdomain is handled by Caddy. Traffic is rewritten internally to the /mcp path on the lnkify server:

mcp.lnkify.io → rewrite to /mcp → server

You can also reach the MCP server directly at https://lnkify.io/mcp in non-production setups.

Next: Authentication