MCP Integration
NewMCP Overview
MCP (Model Context Protocol) lets AI clients call tools instead of guessing APIs from prompt text. For Fynlink, the official implementation is a dedicated MCP server (`fyn-mcp`) backed by the official SDK. That keeps encryption, validation, retries, and response behavior consistent with first-party SDK flows.
This guide covers practical deployment patterns and how popular AI tools can connect to it.
How It Works
Step 1
AI client sends tool call
The AI app invokes MCP tools like `fyn.links.create` or `fyn.analytics.timeseries`.
Step 2
MCP server validates + executes
`fyn-mcp` validates input and routes the operation through the official SDK.
Step 3
Structured result returns
The AI receives deterministic JSON outputs/errors and can continue agent workflows.
Runtime Modes
Local (stdio)
Best for desktop clients and development. The AI app launches the MCP server as a local process and communicates over stdio.
npx -y @fynlink/mcp@latest stdioRemote (HTTP)
Best for shared team environments. Run MCP as a hosted service behind TLS, auth, and rate limits so multiple AI clients can connect.
npx -y @fynlink/mcp@latest http --port 8788
Bearer token support
HTTP mode supports bearer authentication. Set FYN_MCP_BEARER_TOKEN when starting the server, then send Authorization: Bearer ... from the client.
FYN_MCP_BEARER_TOKEN=local_dev_token npx -y @fynlink/mcp@latest http --host 127.0.0.1 --port 8788 --path /mcp
curl http://127.0.0.1:8788/mcp \ -H "Authorization: Bearer local_dev_token" \ -H "Content-Type: application/json"
Setup Examples
ChatGPT
Local-first example using MCP HTTP mode on your machine. Add bearer auth if enabled.
{ "name": "Fynlink MCP", "url": "http://127.0.0.1:8788/mcp", "headers": { "Authorization": "Bearer <FYN_MCP_BEARER_TOKEN>" } }
Claude Desktop
Typical local setup uses stdio with environment variables. This keeps token + secret local to your machine.
{ "mcpServers": { "fynlink": { "command": "npx", "args": ["-y", "@fynlink/mcp@latest", "stdio"], "env": { "FYN_API_TOKEN": "<TOKEN>", "FYN_SECRET_KEY": "<SECRET>" } } } }
Cursor / Cline
Use local stdio or local HTTP MCP depending on your client preference.
{ "mcpServers": { "fynlink": { "transport": "http", "url": "http://127.0.0.1:8788/mcp", "headers": { "Authorization": "Bearer <FYN_MCP_BEARER_TOKEN>" } } } }
Alternative Path
API Hub + OpenAPI (Fallback)
MCP is the best and correct integration path for AI tools because it provides a first-class tool interface with structured invocation and permissions.
If your platform supports OpenAPI import but not MCP, use API Hub as an alternative via its OpenAPI schema endpoint: /openapi.json .
Typical endpoint: https://api-hub.example.com/openapi.json
Tool Surface
Available Tools
| Tool | Purpose |
|---|---|
fyn.info.get | Bootstrap info and permission context |
fyn.links.list | List links with filters |
fyn.links.get | Read one link |
fyn.links.create | Create link via SDK-backed encryption flow |
fyn.links.update | Update mutable link fields |
fyn.analytics.clicks | Fast click count |
fyn.analytics.timeseries | Trend analytics |
Current Coverage
Domains, full analytics, member management, and team operations are already supported. Tool availability maps directly to your token permissions.
Security Model
Keep API token and secret server-side only. Do not expose them in prompts, browser clients, or logs.
Use explicit approval flows for mutation tools (`create`, `update`, `delete`, `invite`, `remove`) whenever the AI client supports approval hooks.
For remote MCP, run behind TLS and add service auth + rate limiting at edge/proxy level.
Prompt Examples
Campaign Link Creation
"Create a link for `https://example.com/spring` on `go.example.com`, analytics `full`, private false, and title `Spring Campaign`."
Performance Review
"For `link_123`, fetch clicks + last 30 days timeseries and summarize top patterns with actionable optimizations."
Domain Ops Checklist
"Create `links.brand.com`, run verification, then output DNS checklist and current status."