---
title: "MCP Server Setup: Claude, Codex, Cursor, VS Code | Appy Docs"
description: "Connect Claude Code, Codex, Cursor, VS Code or Claude Desktop to the Appy MCP server, with the tools, example prompts and security model."
source: "https://appy.to/docs/mcp"
---

Overview

-   [Introduction](https://appy.to/docs)

Links

-   [Custom domains](https://appy.to/docs/custom-domains)
-   [Web banner](https://appy.to/docs/web-banner)
-   [App Store campaigns](https://appy.to/docs/app-store-campaigns)

Account

-   [Team and roles](https://appy.to/docs/team)

Guides

-   [Expo Router](https://appy.to/docs/guides/expo)
-   [FlutterFlow](https://appy.to/docs/guides/flutterflow)

Migrate

-   [Migrate from Branch](https://appy.to/docs/migrate-from-branch)
-   [Migrate from OneLink](https://appy.to/docs/migrate-from-onelink)

SDK

-   [SDK overview](https://appy.to/docs/sdk)
-   [iOS SDK](https://appy.to/docs/sdk/ios)
-   [Android SDK](https://appy.to/docs/sdk/android)
-   [Flutter](https://appy.to/docs/sdk/flutter)
-   [React Native and Expo](https://appy.to/docs/sdk/react-native)
-   [Without the SDK](https://appy.to/docs/sdk/http)
-   [Privacy labels](https://appy.to/docs/sdk/privacy-labels)

Attribution

-   [How attribution works](https://appy.to/docs/attribution)
-   [Ad networks and postbacks](https://appy.to/docs/ad-networks)
-   [SKAdNetwork and AdAttributionKit](https://appy.to/docs/adattributionkit)

API

-   [REST API](https://appy.to/docs/api)

MCP

-   [MCP server](https://appy.to/docs/mcp)

Reference

-   [API reference](https://api.appy.to/docs)
-   [OpenAPI file](https://api.appy.to/v1/openapi.yaml)

Documentation / MCP server

MCP

# MCP server

Appy runs a Model Context Protocol server so AI assistants can create and edit smart links and answer questions about their clicks and installs, with your secret key.

## Endpoint and authentication[#](https://appy.to/docs/mcp#endpoint)

The secret key decides which account the assistant sees. Publishable keys and dashboard sessions get `403 forbidden`.

<table class="w-full border-collapse text-left text-sm"><tbody class="divide-y divide-slate-200"><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Endpoint</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700"><code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">https://mcp.appy.to</code></td></tr><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Transport</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700">Streamable HTTP, stateless, JSON responses. <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">GET</code> and <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">DELETE</code> answer <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">405</code>.</td></tr><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Authentication</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700"><code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">Authorization: Bearer appy_sk_...</code>, a secret key from the dashboard’s <a class="font-medium text-primary underline decoration-primary/30 underline-offset-2 transition-colors hover:decoration-primary" rel="nofollow" href="/dashboard/api">API keys page</a>. <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">initialize</code> and <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">tools/list</code> also answer without a key, so clients and directories can see the tools; every tool call needs the key.</td></tr><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Protocol versions</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700">Negotiated by the server; current clients use 2025-06-18 or later.</td></tr><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Registry name</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700"><code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">to.appy/smart-links</code> in the <a href="https://registry.modelcontextprotocol.io/?q=to.appy" class="font-medium text-primary underline decoration-primary/30 underline-offset-2 transition-colors hover:decoration-primary" target="_blank" rel="noopener noreferrer">official MCP Registry</a>. Clients that read the registry can find the server by that name.</td></tr><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Rate limit</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700">600 requests a minute per key, shared with the key’s <a class="font-medium text-primary underline decoration-primary/30 underline-offset-2 transition-colors hover:decoration-primary" href="/docs/api#rate-limits">REST API</a> calls. Requests without a key: 60 a minute per IP address.</td></tr><tr><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 font-medium text-slate-900">Plans</td><td class="min-w-[8rem] px-4 py-2.5 align-top leading-6 text-slate-700">Business (11 tools) and Enterprise (13 tools). Other plans receive <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.85em] font-normal text-slate-800 break-words">403 plan_required</code>.</td></tr></tbody></table>

Create a dedicated key for each assistant or teammate, so you can revoke one without touching the others.

## Connect a client[#](https://appy.to/docs/mcp#connect-a-client)

1.  1

Create a secret key

On a Business or Enterprise account, open the [API keys page](https://appy.to/dashboard/api) and create a key for this assistant. Name it after where it lives, such as “Claude Code, work laptop”. It starts with `appy_sk_`, is shown once, and an account can hold 10 active keys.

2.  2

Add the server to your client

Use the command or configuration for your client below and replace `appy_sk_...` with your key. The dashboard’s [MCP page](https://appy.to/dashboard/mcp) shows the same snippets.

3.  3

Check the connection

Ask something that changes nothing, such as “Which plan is this key on?”. The assistant calls `get_account`, a read-only tool, and answers with your plan.


### Claude Code[#](https://appy.to/docs/mcp#client-claudecode)

Run this in your terminal. Add `--scope user` to have the server in every project.

terminalCopy

```
claude mcp add --transport http appy https://mcp.appy.to --header "Authorization: Bearer appy_sk_..."
```

### Codex[#](https://appy.to/docs/mcp#client-codex)

Codex saves the server in `~/.codex/config.toml` and reads the key from the `APPY_API_KEY` environment variable, which it sends as a bearer token.

terminalCopy

```
export APPY_API_KEY=appy_sk_...
codex mcp add appy --url https://mcp.appy.to --bearer-token-env-var APPY_API_KEY
```

### Cursor[#](https://appy.to/docs/mcp#client-cursor)

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` inside a project.

~/.cursor/mcp.jsonCopy

```
{
"mcpServers": {
"appy": {
"url": "https://mcp.appy.to",
"headers": {
"Authorization": "Bearer appy_sk_..."
}
}
}
}
```

### VS Code[#](https://appy.to/docs/mcp#client-vscode)

Add this to `.vscode/mcp.json` in your workspace.

.vscode/mcp.jsonCopy

```
{
"servers": {
"appy": {
"type": "http",
"url": "https://mcp.appy.to",
"headers": {
"Authorization": "Bearer appy_sk_..."
}
}
}
}
```

### Claude Desktop and other local-only clients[#](https://appy.to/docs/mcp#client-claudedesktop)

Clients that only start local servers reach the endpoint through the `mcp-remote` bridge, which runs with `npx` and needs Node.js. The header value sits in the `APPY_AUTH` environment variable so the argument has no spaces, which Windows would otherwise split.

claude\_desktop\_config.jsonCopy

```
{
"mcpServers": {
"appy": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.appy.to",
"--header",
"Authorization:${APPY_AUTH}"
],
"env": {
"APPY_AUTH": "Bearer appy_sk_..."
}
}
}
}
```

### Windsurf and other clients[#](https://appy.to/docs/mcp#client-other)

Windsurf and any other client that supports Streamable HTTP take the same URL, `https://mcp.appy.to`, and the same `Authorization` header. Clients that can only start local servers use the `mcp-remote` configuration above.

### Keep the key out of config files[#](https://appy.to/docs/mcp#keep-keys-out-of-files)

The snippets above hold the key in plain text. Two safer variants: Cursor can read it from an environment variable, and VS Code can prompt for it instead of keeping it in the file.

Cursor: key from APPY\_API\_KEYCopy

```
{
"mcpServers": {
"appy": {
"url": "https://mcp.appy.to",
"headers": {
"Authorization": "Bearer ${env:APPY_API_KEY}"
}
}
}
}
```

VS Code: prompt for the keyCopy

```
{
"inputs": [
{
"type": "promptString",
"id": "appy-key",
"description": "Appy secret key",
"password": true
}
],
"servers": {
"appy": {
"type": "http",
"url": "https://mcp.appy.to",
"headers": {
"Authorization": "Bearer ${input:appy-key}"
}
}
}
}
```

Keep keys out of shared repositories. A project-level config such as `.mcp.json`, `.cursor/mcp.json` or `.vscode/mcp.json` is shared with your team: use one of the variants above, add the file to `.gitignore`, or use your client’s support for environment variables.

## Tools[#](https://appy.to/docs/mcp#tools)

Business keys see eleven tools. Enterprise keys see thirteen: `list_apps` and `get_app_attribution` are only listed when the key’s plan includes the SDK, so a Business assistant never offers them. Every tool carries MCP annotations, and none of them reaches outside Appy (`openWorldHint: false`).

| Tool | What it does | Hints | Plan |
| --- | --- | --- | --- |
| `get_account` | Plan, included features (`api`, `mcp`, `sdk`), link limit (`null` means unlimited) and current link count. | read-only | Business |
| `list_links` | Links, newest first, with destinations and targets. `search` matches slug or title; `limit` 1 to 100 (default 20) and `offset` page through the rest. | read-only | Business |
| `get_link` | One link by slug: public `url`, `fallbackUrl`, `deeplinkUrl`, per-platform `targets` and settings. | read-only | Business |
| `create_link` | A new link. The website (`fallbackUrl`) is required; `slug`, `title`, `deeplinkUrl`, `targets` (`iphone`, `ipad`, `android`, `huawei`) and `parameterForwarding` are optional. | additive | Business |
| `update_link` | Changes only the fields you send. An empty string removes `title`, `deeplinkUrl` or a target; targets you leave out stay as they are. | destructive, idempotent | Business |
| `delete_link` | Stops a link from redirecting immediately. The slug stays reserved. | destructive, idempotent | Business |
| `get_link_stats` | Total and unique clicks, clicks per day, and breakdowns by country, OS, device, browser, referrer and outcome (store, app opened, website). | read-only | Business |
| `get_link_timeseries` | Clicks per day for one link, without the breakdowns. | read-only | Business |
| `get_account_stats` | The same totals, daily series and breakdowns across every link in the account. | read-only | Business |
| `get_top_links` | Links ranked by clicks in a date range, best first. `limit` 1 to 100, default 10. | read-only | Business |
| `list_domains` | Custom domains with their status, the DNS record to add, which one is the default for link URLs, and `limits` (`used`, `max`). | read-only | Business |
| `list_apps` | SDK apps with their link domain and iOS and Android identifiers. | read-only | Enterprise |
| `get_app_attribution` | For one app: installs (total, attributed, verified, organic, by store), a row per day, results by UTM source, medium and campaign, in-app events and revenue, and the links that brought them. Optional `link` narrows every number to one link. | read-only | Enterprise |

### Behavior worth knowing[#](https://appy.to/docs/mcp#tool-behavior)

-   Dates are UTC days in `YYYY-MM-DD` form. Without `start` and `end`, statistics cover the last 30 days, ending today.
-   A custom `slug` is 5 to 64 lowercase letters, digits or hyphens; leave it out for a random one. `create_link` refuses a slug that is already taken (`conflict`) instead of overwriting it.
-   The slug of an existing link never changes. Rename by creating a new link and deleting the old one.
-   Deleting a link stops it from redirecting, removes it from your link count and keeps the slug reserved, so nobody else can claim it.
-   Revenue from `get_app_attribution` is summed per currency, as the app reports it.
-   Every tool returns structured content and the same result as JSON text, so clients without structured output support still work.
-   Deleting installs or user data is not available through MCP; use the [REST API](https://appy.to/docs/api#deleting-installs).

## Errors[#](https://appy.to/docs/mcp#errors)

Errors reach the assistant in two ways. Problems with the key are answered at the HTTP level, before any tool runs, with the same JSON error body as the [REST API](https://appy.to/docs/api#errors). Clients usually show these as a failed connection.

| Status | `code` | When |
| --- | --- | --- |
| 401 | `unauthorized` | A tool was called without an `Authorization` header, or the key is unknown or revoked. Listing the tools works without a key. |
| 403 | `forbidden` | A dashboard session or a publishable key was sent instead of a secret key. |
| 403 | `plan_required` | The account is below Business. |
| 429 | `rate_limited` | The key used up its 600 requests for the minute. Honor `Retry-After`. |

Problems inside a call come back as a tool error whose text starts with the API error code, followed by the message, so the assistant can explain what went wrong in plain words:

tool errorCopy

```
conflict: This slug is already in use. Choose another one.
```

| `code` | Typical cause |
| --- | --- |
| `validation_failed` | A value is not acceptable, for example a website (`fallbackUrl`) that is not an http(s) URL. |
| `not_found` | The slug or app does not exist, was deleted, or belongs to another account. |
| `conflict` | The slug is already taken. |
| `limit_reached` | The account is at its link limit. |
| `internal_error` | Something failed on Appy’s side. Reads are safe to retry. |

## What the assistant calls[#](https://appy.to/docs/mcp#worked-example)

Nobody names a tool. On connect the assistant receives every tool’s description and input schema plus the server’s short instructions (read a link before changing it, confirm before deleting one), then picks a tool for each step and fills in the arguments. Three requests, start to finish. The account, links and numbers are made up.

### Copy a link for a new campaign[#](https://appy.to/docs/mcp#example-copy-link)

Request: “Make a copy of spring-sale for the autumn campaign that opens `acme://sale/autumn` in the app, with acme.com/autumn as the website.”

The assistant reads the original first, so it can reuse its store targets. `get_link` is read-only, so clients run it without asking.

get\_link · argumentsCopy

```
{
"slug": "spring-sale"
}
```

get\_link · resultCopy

```
{"slug": "spring-sale",
 "url": "https://appy.to/spring-sale",
 "deeplinkUrl": "acme://sale/spring",
 "targets": {"iphone": "https://apps.apple.com/app/id123456789",
"android": "https://play.google.com/store/apps/details?id=com.acme.shop"},
 ...}
```

Then it creates the copy. `create_link` is additive: it can only add a link, and a taken slug is refused rather than overwritten.

create\_link · argumentsCopy

```
{
"slug": "autumn-sale",
"fallbackUrl": "https://acme.com/autumn",
"deeplinkUrl": "acme://sale/autumn",
"targets": {
"iphone": "https://apps.apple.com/app/id123456789",
"android": "https://play.google.com/store/apps/details?id=com.acme.shop"
}
}
```

create\_link · resultCopy

```
{"slug": "autumn-sale",
 "url": "https://appy.to/autumn-sale",
 "createdAt": "2026-09-25T10:00:00Z",
 ...}
```

Reply: “autumn-sale is live at appy.to/autumn-sale, with the same App Store and Google Play pages as spring-sale.”

### Rank links by clicks[#](https://appy.to/docs/mcp#example-top-links)

Request: “Which three links got the most clicks last week?” The assistant turns “last week” into UTC dates and asks for three results.

get\_top\_links · argumentsCopy

```
{
"start": "2026-09-14",
"end": "2026-09-20",
"limit": 3
}
```

get\_top\_links · resultCopy

```
{"start": "2026-09-14", "end": "2026-09-20",
 "data": [
{"slug": "spring-sale", "title": null, "clicks": 4812},
{"slug": "app-download", "title": "App download", "clicks": 2236},
{"slug": "newsletter-sep", "title": null, "clicks": 1390}
 ],
 ...}
```

### Delete with confirmation[#](https://appy.to/docs/mcp#example-delete)

Request: “Delete our test links.” The assistant looks first:

list\_links · argumentsCopy

```
{
"search": "test"
}
```

list\_links · resultCopy

```
{"links": [{"slug": "spring-test", ...}, {"slug": "qr-test", ...}],
 "total": 2, "limit": 20, "offset": 0}
```

It then asks: “Two links match: spring-test and qr-test. Deleting stops them from redirecting. Delete both?” The user answers “Only spring-test.” Because `delete_link` carries the destructive hint, the client also asks for approval before it runs the call.

delete\_link · argumentsCopy

```
{
"slug": "spring-test"
}
```

delete\_link · resultCopy

```
{"slug": "spring-test", "deleted": true}
```

## Example prompts[#](https://appy.to/docs/mcp#example-prompts)

-   “Create a link called spring-sale that opens `acme://sale/spring` in our app, sends iPhones to our App Store page and Android phones to Google Play, and everyone else to acme.com/spring.”
-   “Which five links had the most clicks last week, and where did the clicks on the top one come from?”
-   “Compare daily clicks on `spring-sale` and `summer-sale` for September.”
-   “Point every link whose website is the old campaign page at the new one.” The assistant lists the links first and asks before changing them.
-   On Enterprise: “How many installs did the spring campaign bring last month, how many installs were organic, and what did the spring installs spend?”

## Guardrails and security[#](https://appy.to/docs/mcp#security)

-   A key acts as its account and nothing else. The MCP server sees exactly what the [REST API](https://appy.to/docs/api) sees for that account; a slug from another account comes back as `not_found`.
-   `update_link` and `delete_link` carry MCP’s destructive hint, so clients that honor it ask before running them. Read tools are marked read-only, and `create_link` only adds.
-   The server’s instructions tell the assistant to read a link before changing it and to confirm with the user before deleting one.
-   Keys cannot create or revoke keys. `/v1/api-keys` only accepts a signed-in dashboard session, so an assistant can never hand out access.
-   Dashboard sessions and publishable keys are refused by the MCP server with `403 forbidden`.
-   The server keeps no MCP session state. Every request is authenticated and plan-checked on its own.
-   Revoking a key in the dashboard stops the assistant with the next request. A downgrade below Business does the same with `403 plan_required`; the keys stay listed, so you can still revoke them.
-   Each key has its own limit of 600 requests a minute, shared with its REST calls. An assistant stuck in a loop only exhausts its own key.
-   OAuth sign-in for clients that cannot send headers, such as web chat connectors, is not available yet.

[PreviousREST API](https://appy.to/docs/api)

On this page

-   [Endpoint and authentication](https://appy.to/docs/mcp#endpoint)
-   [Connect a client](https://appy.to/docs/mcp#connect-a-client)
-   [Tools](https://appy.to/docs/mcp#tools)
-   [Errors](https://appy.to/docs/mcp#errors)
-   [What the assistant calls](https://appy.to/docs/mcp#worked-example)
-   [Example prompts](https://appy.to/docs/mcp#example-prompts)
-   [Guardrails and security](https://appy.to/docs/mcp#security)
