LinkForty Documentation

MCP Server

Connect Claude, Cursor, Claude Code, and any other MCP-compatible AI tool to your LinkForty workspace. Manage links, query analytics, and integrate the mobile SDK using natural language.

Open Source

The LinkForty MCP server is open source and free to use on every plan, including Free. Source code: github.com/linkforty/mcp-server · npm: @linkforty/mcp-server

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. It works like a universal adapter — any MCP-compatible AI client can talk to any MCP server using the same protocol.

The LinkForty MCP server exposes your workspace to your AI assistant as a set of 20 tools. When you ask Claude something like "create a deep link for my Spring sale", the AI calls the create_link tool, which makes an authenticated HTTP request to the LinkForty API and returns the result.

The server supports two connection modes:

HTTP transport (recommended) — connect via a URL. No local installation, no Node.js required. Works like any other hosted MCP server (Linear, Google, etc.).
stdio transport — runs locally on your machine as a subprocess of your AI client. Requires Node.js 18+.

Why use it

Once connected, you can ask your AI assistant to do things like:

"Create a LinkForty deep link for my Spring sale on Instagram with UTM source=instagram, medium=social, campaign=spring-sale"
"Which links drove the most installs last week?"
"Show me click trends for my top 5 links over the last 30 days"
"Why is link xyz123 getting clicks but no installs?"
"Help me add the LinkForty SDK to my React Native app"
"Create 50 deep links from this CSV"
"What's my install attribution rate this month?"

The AI calls the appropriate LinkForty tools behind the scenes and returns structured results — no manual API requests, no copy-pasting JSON, no leaving your editor or chat window.

Supported AI clients

Client	HTTP transport	stdio transport	Project-level config
Claude Desktop	✅	✅	❌ (global only)
Cursor	✅	✅	✅ (`.cursor/mcp.json`)
Claude Code	✅	✅	✅ (`.mcp.json`)
Any other MCP-compatible client	✅	✅	Depends on the client

Quick start

1. Get your API key

Sign in to your LinkForty dashboard, go to Workspace Settings → API Keys, and create a new key. Copy the value (it starts with dl_).

One key, one workspace

LinkForty API keys are scoped to a single workspace. If you manage multiple workspaces, create one key per workspace and run multiple MCP server instances if you need them all available simultaneously.

2. Add the MCP server to your AI client

Pick your client and transport mode. Replace dl_your_api_key_here with your actual API key.

HTTP transport (recommended)

No local installation required — just a URL and your API key. This is the same setup pattern used by Linear, Google, and other hosted MCP servers.

Claude Desktop

Edit your claude_desktop_config.json file:

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

{
  "mcpServers": {
    "linkforty": {
      "type": "http",
      "url": "https://mcp.linkforty.com/mcp",
      "headers": {
        "Authorization": "Bearer dl_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The 20 LinkForty tools will appear in the tool picker.

Cursor

Open Cursor → Settings → MCP Servers and add:

{
  "linkforty": {
    "type": "http",
    "url": "https://mcp.linkforty.com/mcp",
    "headers": {
      "Authorization": "Bearer dl_your_api_key_here"
    }
  }
}

Claude Code

Run from your terminal:

claude mcp add linkforty \
  --transport http \
  --url https://mcp.linkforty.com/mcp \
  --header "Authorization: Bearer dl_your_api_key_here"

stdio transport (local)

Runs the MCP server as a local Node.js subprocess. Requires Node.js 18+.

Claude Desktop

Edit your claude_desktop_config.json file:

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

{
  "mcpServers": {
    "linkforty": {
      "command": "npx",
      "args": ["-y", "@linkforty/mcp-server"],
      "env": {
        "LINKFORTY_API_KEY": "dl_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The 20 LinkForty tools will appear in the tool picker.

Cursor

Open Cursor → Settings → MCP Servers and add:

{
  "linkforty": {
    "command": "npx",
    "args": ["-y", "@linkforty/mcp-server"],
    "env": {
      "LINKFORTY_API_KEY": "dl_your_api_key_here"
    }
  }
}

Claude Code

Run from your terminal:

claude mcp add linkforty \
  -e LINKFORTY_API_KEY=dl_your_api_key_here \
  -- npx -y @linkforty/mcp-server

3. Try it

Open a new chat and ask your AI assistant something like:

Show me my top 5 links from the last 30 days and tell me which countries they're getting traffic from.

You should see the AI call get_overview_analytics (or get_top_links) and return real data from your workspace.

Project-level setup (advanced)

For Cursor and Claude Code, you can scope the MCP server to a single project instead of running it globally. This is useful when:

You only use LinkForty inside one specific app's repository
Your team wants every developer to have the same MCP setup automatically (commit the config to git)
You manage multiple LinkForty workspaces and want different repos to use different ones

Don't commit your API key

The config snippets below reference an environment variable instead of hardcoding the key, so the file is safe to check into git. Set LINKFORTY_API_KEY in your shell, .envrc, or a gitignored .env.local file.

Claude Code (`.mcp.json`)

Create a .mcp.json file in your project root. Claude Code will pick it up automatically when you open the directory.

HTTP transport:

{
  "mcpServers": {
    "linkforty": {
      "type": "http",
      "url": "https://mcp.linkforty.com/mcp",
      "headers": {
        "Authorization": "Bearer ${LINKFORTY_API_KEY}"
      }
    }
  }
}

stdio transport:

{
  "mcpServers": {
    "linkforty": {
      "command": "npx",
      "args": ["-y", "@linkforty/mcp-server"],
      "env": {
        "LINKFORTY_API_KEY": "${LINKFORTY_API_KEY}"
      }
    }
  }
}

Cursor (`.cursor/mcp.json`)

Create a .cursor/mcp.json file in your project root. Cursor will load it whenever the project is open.

HTTP transport:

{
  "mcpServers": {
    "linkforty": {
      "type": "http",
      "url": "https://mcp.linkforty.com/mcp",
      "headers": {
        "Authorization": "Bearer ${LINKFORTY_API_KEY}"
      }
    }
  }
}

stdio transport:

{
  "mcpServers": {
    "linkforty": {
      "command": "npx",
      "args": ["-y", "@linkforty/mcp-server"],
      "env": {
        "LINKFORTY_API_KEY": "${LINKFORTY_API_KEY}"
      }
    }
  }
}

Setting the environment variable locally

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
export LINKFORTY_API_KEY=dl_your_api_key_here

# Or with direnv (recommended for project-scoped secrets):
echo 'export LINKFORTY_API_KEY=dl_your_api_key_here' >> .envrc
direnv allow

# Or use a gitignored .env.local file your shell loads on cd

Available tools

The LinkForty MCP server exposes 20 tools across 6 categories:

Links (6 tools)

Tool	Description
`create_link`	Create a new deep link with iOS/Android/web URLs, UTM, targeting, and more
`list_links`	List/filter links by status, source, project, search query, or date range
`get_link`	Get a single link by ID or short code
`update_link`	Update any field on an existing link
`delete_link`	Permanently delete a link
`bulk_create_links`	Create up to 100 links in one call

Analytics (5 tools)

Tool	Description
`get_link_analytics`	Per-link analytics: clicks, geo, devices, time series
`get_overview_analytics`	Workspace-wide analytics across all links
`get_top_links`	Top performing links ranked by clicks
`get_install_attribution`	Install attribution data with fingerprint matching
`get_funnel`	Click → install → event conversion funnel

Templates (3 tools)

Tool	Description
`list_templates`	List all link templates
`create_template`	Create a new template with default destinations and UTM
`set_default_template`	Mark a template as the workspace default

Projects (2 tools)

Tool	Description
`list_projects`	List all projects in the workspace
`create_project`	Create a new project for grouping links

Workspace (3 tools)

Tool	Description
`list_workspaces`	List workspaces accessible by the API key
`get_current_workspace`	Get details about the current workspace
`get_app_config`	Get iOS/Android bundle IDs, schemes, link domains

SDK helper (1 tool)

Tool	Description
`get_sdk_install_snippet`	Generate ready-to-paste SDK init code for any platform (react-native, expo, ios, android, flutter), pre-filled with your API key and app config

Configuration reference

HTTP transport

With the HTTP transport, there are no environment variables to set on the client side. Your API key is passed in the Authorization header.

If you're self-hosting the MCP HTTP server, the following environment variables apply to the server process:

Environment variable	Required	Default	Description
`PORT`	No	`3001`	HTTP server port
`LINKFORTY_BASE_URL`	No	`https://api.linkforty.com/api`	Override for self-hosted LinkForty Core instances

stdio transport

Environment variable	Required	Default	Description
`LINKFORTY_API_KEY`	Yes	—	Your LinkForty workspace API key (starts with `dl_`)
`LINKFORTY_BASE_URL`	No	`https://api.linkforty.com/api`	Override for self-hosted LinkForty Core instances

Self-hosted LinkForty Core

If you're running LinkForty Core on your own infrastructure, point the MCP server at your instance.

HTTP transport — host the MCP HTTP server yourself and set LINKFORTY_BASE_URL:

LINKFORTY_BASE_URL=https://your-instance.com/api PORT=3001 npx -y @linkforty/mcp-server-http

Then configure your client to point to your hosted URL instead of mcp.linkforty.com.

stdio transport — set the base URL in the env block:

{
  "mcpServers": {
    "linkforty": {
      "command": "npx",
      "args": ["-y", "@linkforty/mcp-server"],
      "env": {
        "LINKFORTY_API_KEY": "dl_your_api_key_here",
        "LINKFORTY_BASE_URL": "https://your-instance.com/api"
      }
    }
  }
}

Security and privacy

The MCP server is designed with strict security boundaries:

No data is stored or logged by the MCP server. It's a stateless translator between MCP requests and LinkForty's REST API. Every tool call is a fresh HTTP request. There's no telemetry, no analytics, no third parties.
API keys inherit your workspace permissions. The MCP server can only do what your API key has permission to do — there's no privilege escalation. If your role is viewer, the AI assistant can only call read-only tools.
API keys are scoped to a single workspace. An API key for Workspace A cannot read or modify Workspace B's data, even if you own both.

stdio mode: The MCP server runs locally as a subprocess of your AI client. Your API key is stored in your local config file and only sent to the LinkForty API endpoint.

HTTP mode: Your API key is sent in the Authorization header to the hosted MCP endpoint (mcp.linkforty.com), which forwards it to the LinkForty API. The MCP server does not store, log, or cache API keys. All communication uses HTTPS.

Troubleshooting

"Tool not found" or no LinkForty tools appear

Make sure you restarted your AI client after editing the config file
Check that the JSON in your config file is valid (run it through jsonlint.com if unsure)
Verify that npx is on your PATH — try running npx -y @linkforty/mcp-server directly in a terminal. It should print an error about the missing API key, which means the package can be downloaded and run.

"API key authentication failed" or 401 errors

Verify the key is correct and active in your dashboard at Workspace Settings → API Keys
Make sure you copied the full key (they start with dl_ followed by 64 hex characters)
If you regenerated the key, make sure you updated your AI client config with the new value

Tools work but return empty data

The API key is bound to one workspace — if you have multiple, make sure you're using the key for the workspace you expect
Check that your workspace actually has data (links, clicks, installs). New workspaces will return empty arrays.

"Cannot find module" or npm download errors

Make sure you have Node.js 18 or later installed: node --version
Try clearing the npx cache: npx clear-npx-cache
Try installing globally as a workaround: npm install -g @linkforty/mcp-server, then change command to linkforty-mcp in your config

Source and contributions

GitHub: github.com/LinkForty/mcp-server
npm: @linkforty/mcp-server
License: MIT
Issues: github.com/LinkForty/mcp-server/issues

The MCP server is open source. Pull requests welcome — especially for additional tools, support for more AI clients, or quality-of-life improvements.

API Authentication — How API keys work in LinkForty
Webhooks — Real-time event delivery to your own server
Analytics Integrations — Forward events to Mixpanel, Amplitude, GA4, and more
Model Context Protocol — The open standard the MCP server is built on

What is MCP?​

Why use it​

Supported AI clients​

Quick start​

1. Get your API key​

2. Add the MCP server to your AI client​

HTTP transport (recommended)​

stdio transport (local)​

3. Try it​

Project-level setup (advanced)​

Claude Code (.mcp.json)​

Cursor (.cursor/mcp.json)​

Setting the environment variable locally​

Available tools​

Links (6 tools)​

Analytics (5 tools)​

Templates (3 tools)​

Projects (2 tools)​

Workspace (3 tools)​

SDK helper (1 tool)​

Configuration reference​

HTTP transport​

stdio transport​

Self-hosted LinkForty Core​

Security and privacy​

Troubleshooting​

"Tool not found" or no LinkForty tools appear​

"API key authentication failed" or 401 errors​

Tools work but return empty data​

"Cannot find module" or npm download errors​

Source and contributions​

Related​