@fynlink/mcp

v0.1.0

Published

3 months ago

Official MCP server for Fynlink powered by @fynlink/sdk.

0High
0Medium
0Low

nbk.dev

Fynlink MCP (`@fynlink/mcp`)

Official MCP server for Fynlink, powered by the official @fynlink/sdk.

Why this exists

fyn-mcp gives AI clients a standard MCP tool surface for Fynlink operations without reimplementing encryption, retries, or API request shaping.

It is useful when:

your AI platform supports MCP natively
your app stack does not have a first-party Fyn SDK yet
you want one secure integration point for AI-assisted link/domain/team workflows

Features

Uses official @fynlink/sdk internally
Strict input schemas with zod
Permission-aware tool gating (fyn.info.get().permissions)
In-memory rate limiting for tool calls
Redacted structured logging (token/secret/password-safe)
MCP resources + prompts in addition to tools
Supports:
- stdio mode (local clients)
- stateless Streamable HTTP mode (remote clients)

Tool Surface

Info

fyn.info.get

Analytics

fyn.analytics.clicks
fyn.analytics.timeseries
fyn.analytics.browsers
fyn.analytics.devices
fyn.analytics.countries
fyn.analytics.referrers

Domains

fyn.domains.list
fyn.domains.get
fyn.domains.create
fyn.domains.update
fyn.domains.verify
fyn.domains.remove

Members

fyn.members.list
fyn.members.get
fyn.members.invite
fyn.members.update
fyn.members.remove

Teams

fyn.teams.get
fyn.teams.update

Resources

fyn://team/current
fyn://links/recent
fyn://domains/list

Prompts

create-campaign-link
analyze-link-performance
domain-verification-checklist

Install

npm install @fynlink/mcp

Required Environment

FYN_API_TOKEN=token_xxx

Optional:

FYN_SECRET_KEY=
FYN_TIMEOUT_MS=10000
FYN_RETRY_MAX_ATTEMPTS=2
FYN_RETRY_INITIAL_DELAY_MS=1000
FYN_CACHE_ENABLED=true
FYN_CACHE_TTL_MS=300000
FYN_CACHE_STORAGE=memory
FYN_CACHE_PATH=
FYN_CACHE_WARN_ON_DISK=false
FYN_DEBUG=false

SDK create defaults (optional):

FYN_DEFAULT_CREATE_DOMAIN=
FYN_DEFAULT_CREATE_SAFE_MODE=
FYN_DEFAULT_CREATE_ANALYTICS=
FYN_DEFAULT_CREATE_PRIVATE_LINK=
FYN_DEFAULT_CREATE_EXPIRY_SECONDS=

MCP server runtime:

FYN_MCP_SERVER_NAME=fyn-mcp
FYN_MCP_SERVER_VERSION=
FYN_MCP_LOG_LEVEL=info
FYN_MCP_PERMISSION_CACHE_TTL_MS=60000
FYN_MCP_RATE_LIMIT_WINDOW_MS=60000
FYN_MCP_RATE_LIMIT_MAX_CALLS=180

HTTP mode options:

FYN_MCP_HTTP_HOST=127.0.0.1
FYN_MCP_HTTP_PORT=8788
FYN_MCP_HTTP_PATH=/mcp
FYN_MCP_HTTP_ENABLE_JSON_RESPONSE=true
FYN_MCP_HTTP_CORS_ORIGIN=*
FYN_MCP_BEARER_TOKEN=

HTTP Bearer Token (optional, recommended)

Yes. MCP HTTP mode supports bearer-token protection via FYN_MCP_BEARER_TOKEN.

Start server with a token:

FYN_MCP_BEARER_TOKEN=local_dev_token npx -y @fynlink/mcp http --host 127.0.0.1 --port 8788 --path /mcp

Call MCP endpoint with header:

curl http://127.0.0.1:8788/mcp \
  -H "Authorization: Bearer local_dev_token" \
  -H "Content-Type: application/json"

Run

Local stdio (recommended for desktop MCP clients)

npx -y @fynlink/mcp stdio

Remote HTTP

npx -y @fynlink/mcp http --host 0.0.0.0 --port 8788 --path /mcp

Health endpoint:

GET /health

Docker

docker build -t fynlink/mcp:local .
docker run --rm -p 8788:8788 --env-file .env fynlink/mcp:local

or:

docker compose up --build

AI Client Examples

Claude Desktop (`stdio`)

{
  "mcpServers": {
    "fynlink": {
      "command": "npx",
      "args": ["-y", "@fynlink/mcp", "stdio"],
      "env": {
        "FYN_API_TOKEN": "token_xxx",
        "FYN_SECRET_KEY": "secret_xxx"
      }
    }
  }
}

Cursor / Cline (`http`)

{
  "mcpServers": {
    "fynlink": {
      "transport": "http",
      "url": "http://127.0.0.1:8788/mcp",
      "headers": {
        "Authorization": "Bearer <FYN_MCP_BEARER_TOKEN>"
      }
    }
  }
}

OpenAI MCP connector (`http`)

Local-first example:

{
  "name": "Fynlink MCP",
  "url": "http://127.0.0.1:8788/mcp",
  "headers": {
    "Authorization": "Bearer <FYN_MCP_BEARER_TOKEN>"
  }
}

Security Notes

Keep FYN_API_TOKEN and FYN_SECRET_KEY server-side only.
For HTTP mode, set FYN_MCP_BEARER_TOKEN and terminate TLS at edge/proxy.
Run behind rate limiting + WAF in production.
Logs are redacted for sensitive fields.

Development

npm install
npm run dev
npm run lint
npm run typecheck
npm test
npm run build
npm run pack:check
npm run release:check

Release

CI validates typecheck, test, build, and pack:check on pushes/PRs to main.
Publish runs only on git tags matching v*.
Publish requires npm auth via NPM_TOKEN (or NODE_AUTH_TOKEN) repository secret.
Tag must match package.json version exactly (example: v0.1.0 for 0.1.0).