MCP Integration

The fyrn MCP server lets AI agents manage your integrations through natural conversation. Agents can list flows, create new integrations, deploy, monitor, and troubleshoot — all through the Model Context Protocol.

What MCP is

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. fyrn’s MCP server exposes 49 tools across three permission tiers, giving AI agents structured access to the platform.

• NPM package: @fyrn/mcp-server
• Transports: stdio (default, for Claude Desktop) and SSE (for web integrations)

---

Setting up the fyrn MCP server

Installation

The server is published to the public npm registry. No explicit install step is needed for the standard Claude Desktop setup — npx pulls and runs the latest version on first launch.

For environments where pre-installation is preferred:

npm install -g @fyrn/mcp-server
# then invoke as: fyrn-mcp

Claude Desktop configuration

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

claude_desktop_config.json

{
  "mcpServers": {
    "fyrn": {
      "command": "npx",
      "args": ["@fyrn/mcp-server"],
      "env": {
        "FYRN_AGENT_KEY": "<your-agent-key>",
        "FYRN_API_URL": "https://api.fyrn.ai"
      }
    }
  }
}

Get your agent key from the fyrn dashboard under Settings → Agent Keys. Each key carries its tier, rate limit, daily quota, and approval mode; the server reads these via POST /api/v1/agent-keys/validate on startup.

Environment variables

Variable	Required	Default	Description
FYRN_AGENT_KEY	Yes (stdio)	—	Agent API key. In SSE mode it can come from the Authorization: Bearer header or ?agent_key= query param instead.
FYRN_API_URL	No	https://api.fyrn.ai	Control-plane base URL. Also accepts FYRN_CONTROL_PLANE_URL as an alias.
FYRN_ENVIRONMENT_ID	No	—	Pin the MCP session to a specific environment. Sent as X-Environment-Id on every request. If omitted, the environment on the agent key is used.
MCP_PORT	No	3100	Port for SSE transport.

Transport modes

stdio (default) — communicates over stdin/stdout; used by Claude Desktop and most MCP clients:

fyrn-mcp --transport stdio

SSE — HTTP Server-Sent Events for web integrations. The agent key is supplied per request, so one server instance can serve many users:

fyrn-mcp --transport sse

---

Permission tiers

Tier	Label	What agents can do
1	Use	List flows, search, inspect status, trigger flows, call published APIs, view schedules, test adapters, view lookups
2	Build	Everything in tier 1, plus: create/update instances, create flows, deploy, create adapters, create/update published APIs and services, create lookups, start batches
3	Manage	Everything in tier 2, plus: edit flows, pause/resume, retry messages, manage healing, update schedules, delete published APIs and lookups

---

Approval gate

Tools that create or modify resources (tier 2–3) require human approval by default:

1. Agent calls the tool without approval_id.
2. Server creates a pending action (1-hour expiry) and returns its approval_id. In the same response the server polls for the approval result for up to 5 minutes at 2-second intervals.
3. If the reviewer approves within that window, the tool’s real handler runs and returns the result to the agent.
4. If the poll times out, the response includes { status: "approval_timeout", action_id }. The agent can re-call the tool with approval_id set once the action has been approved.
5. Rejected or expired actions surface as errors.

Agent keys with approvalMode: "autonomous" skip the gate entirely; strict mode gates every tier-2+ tool, regardless of the per-tool flag.

---

All available tools

Tier 1 — Use (17 tools, read-only + trigger)

Tool	Description
list_environments	List account environments (dev/staging/production) — resolves env IDs for clone_flow
list_flows	List integration flows with status, metrics, and env context (envSlug, accountSlug)
search_flows	Search flows by name or description
get_flow_status	Get a flow’s current status and recent metrics (message counts, success rate, latency)
trigger_flow	Send a payload through a flow (supports name resolution)
list_published_apis	List published API endpoints — includes internal path and serving-URL publicUrl
list_published_services	List published services (grouped API actions)
call_published_api	Send data to a published API endpoint at /published/{accountSlug}/{envSlug}/v{version}/{path}
get_api_spec	Retrieve OpenAPI spec (JSON or YAML) for a published API
list_schedules	List scheduled flows with cron, next run, and status
get_batch_status	Get status/progress of a batch job
list_batch_jobs	List recent batch jobs
export_batch_errors	Export failed/retried-failed records for a batch job
list_adapters	List custom code adapters with type and test status
test_adapter	Test an adapter in a sandboxed V8 isolate
list_lookups	List lookup tables (account-scoped, shared across environments)
get_lookup	Get a lookup table with its entries

Tier 2 — Build (20 tools, create + deploy)

Tool	Approval	Description
list_catalog	No	List connector catalog — summary view (no actions/openApiSpec) to stay under 1 MB
get_catalog_entry	No	Fetch a single catalog entry with full details (including actions and oauthConfig)
test_instance	No	Test a connector instance connection
preview_flow	No	Preview payload transformation without delivery
create_instance	Yes	Create a connector instance with encrypted credentials
update_instance	Yes	Update an existing connector instance
create_flow	Yes	AI-generated — generate a flow from natural language
clone_flow	Yes	Clone a flow to another environment (use list_environments to find target IDs)
deploy_flow	Yes	Validate, compile, and activate a flow
create_published_api	Yes	AI-generated — generate a published API endpoint
update_published_api	Yes	Update a published API endpoint
create_published_service	Yes	Create a published service grouping
create_service_action	Yes	Add an action to a published service
trigger_schedule	Yes	Manually trigger a scheduled flow
start_batch	Yes	Start a batch processing job
retry_batch_failed_records	Yes	Retry failed records in a batch job
create_adapter	Yes	AI-generated — create a custom code adapter
create_lookup	Yes	Create a lookup table
set_lookup_entry	No	Set a key/value in a lookup table
import_lookup_csv	No	Import CSV into a lookup table

Tier 3 — Manage (12 tools, operations + full access)

Tool	Approval	Description
get_messages	No	View message logs for a flow (with PII filtering)
pause_flow	No	Pause an active flow
resume_flow	No	Resume a paused flow
retry_message	No	Retry delivery of a failed message
list_healing_events	No	List self-healing events
edit_flow	Yes	Edit an existing flow’s configuration
approve_healing	Yes	Approve a pending self-healing fix
update_schedule	Yes	Update cron, timezone, or enable/disable a schedule
update_adapter	Yes	Update an existing custom code adapter
delete_published_api	Yes	Delete a published API endpoint
delete_lookup	Yes	Delete a lookup table
delete_lookup_entry	Yes	Delete an entry from a lookup table

AI-powered tools

Three tools invoke Claude to generate configuration from natural language:

• create_flow — natural language to integration flow
• create_published_api — description to published API endpoint
• create_adapter — description to custom code adapter (V8 sandboxed)

See MCP Tools Reference for complete parameter details and JSON examples.

---

Scoping model

• Account-scoped resources (shared across environments): lookup tables, connector catalog, adapters. A lookup referenced by a flow in staging is the same data in production after clone_flow — no rewiring needed.
• Environment-scoped resources: flows, connector instances, published APIs, schedules, batch jobs, message logs. Each carries an environmentId; list/read responses also expose envSlug (and accountSlug for the containing account).

Response enrichments

List and read endpoints return stable IDs and human-readable identifiers so agents don’t have to cross-reference UUIDs:

Endpoint	Extra fields
list_flows, get_flow_status	envSlug, envName, accountSlug, webhookUrl (if trigger is webhook)
list_published_apis, GET /published-apis/:id	accountSlug, envSlug, publicUrl, docsUrl
list_lookups	accountSlug (lookups are account-scoped; no envSlug)

publicUrl vs path: Published APIs store path as the internal /inbound/... prefix used by the DB lookup. publicUrl is the fully qualified serving URL — /published/{accountSlug}/{envSlug}/v{version}/{path} — that consumers actually POST to. Always prefer publicUrl when telling a human or external system where to send requests.

list_catalog vs get_catalog_entry: The list endpoint returns a summary projection to stay under the 1 MB MCP response limit. To inspect a catalog entry’s actions array or oauthConfig, call get_catalog_entry with the entry ID.

---

Example conversation

Here’s how an agent might build and deploy a flow:

User: Create a flow that syncs new Shopify orders to our NetSuite ERP

Agent: I’ll create that integration. Let me generate the flow… calls create_flow with description

Agent: I’ve generated a flow that maps Shopify order fields to NetSuite sales orders. Here’s the YAML — would you like me to deploy it?

User: Yes, deploy it

Agent: calls deploy_flow — requires approval

Agent: The deployment needs your approval. Please review and approve in the fyrn dashboard.

(Human approves)

Agent: calls deploy_flow with approval_id — deployed!

Agent: Your flow is live. Webhook URL: https://api.fyrn.dev/webhooks/receive/abc123. New Shopify orders will automatically sync to NetSuite.

---

Security & governance

• 3-tier permission system — Use / Build / Manage with optional per-key tool whitelisting
• Approval gates — mutating tools require human approval via the pending-action flow above
• Rate limiting — per-minute and daily quota enforcement per agent key
• Loop detection — blocks agents calling the same tool with identical inputs 5+ times in 60s
• PII filtering — auto-masks emails, phones, SSNs, and sensitive fields unless explicitly granted access
• Credential masking — API keys, tokens, passwords never returned unmasked
• Audit logging — structured JSON logs for every tool call with status, duration, and agent identity

PII field detection

get_flow_status and related responses include piiFields. This is auto-compiled at deploy time from the flow config’s policies block (pii-mask, pii-encrypt, pii-strip). piiFields: null means the flow has no PII policies declared — it is not an “unknown” state.

---

Errors

The server surfaces errors as MCP tool responses with isError: true and a single text content block. Common categories:

• Permission denied — agent tier doesn’t cover the requested tool.
• Unknown tool: <name> — the tool name isn’t registered. If you see this for a tool the docs list, it indicates a permission-matrix drift bug and should be reported.
• Rate limit exceeded — per-minute or daily quota hit.
• Loop detected — same tool + identical args called 5+ times in 60s.
• Action was rejected by a reviewer — approval flow denied.
• Pending action <id> is not approved (current status: …) — agent re-called with an approval_id that isn’t yet approved.

Some MCP clients (including Claude’s tool_search) load tool schemas on demand and may show tools as “not loaded” mid-session. This is a client-side affordance, not a server issue — the server registers all 49 tools at startup.

---

What’s next

• MCP Tools Reference — Complete parameter and example reference
• CLI Usage — CLI alternative for the same operations
• Creating Flows — Build flows with AI or manually