MCP server

Endpoint and authentication#

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

Connect a client#

1. 1

   Create a secret key

   On a Business or Enterprise account, open the API keys page 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 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#

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

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

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.

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

Cursor#

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

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

VS Code#

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

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

Claude Desktop and other local-only clients#

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.

{
  "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#

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#

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.

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

{
  "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}"
      }
    }
  }
}

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).

Behavior worth knowing#

• 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.

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. Clients usually show these as a failed connection.

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:

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

What the assistant calls#

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#

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.

{
  "slug": "spring-sale"
}

{"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.

{
  "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"
  }
}

{"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#

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

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

{"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#

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

{
  "search": "test"
}

{"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.

{
  "slug": "spring-test"
}

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

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#

• A key acts as its account and nothing else. The MCP server sees exactly what the REST 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.