MCP Tools

The fyrn MCP server exposes 41 tools for AI agents to manage the integration platform. It follows the Model Context Protocol specification and works with Claude Desktop, custom agents, and any MCP-compatible client.

Permission tiers

Tier	Label	Description
1	Use	Read-only + trigger. List, search, inspect, and send payloads through existing flows.
2	Build	Read + create. Create instances, flows, adapters, published APIs, and lookup tables.
3	Manage	Full access. Edit flows, pause/resume, retry messages, manage healing, update schedules.

Tools that require approval use a two-step pattern:

1. Agent calls the tool without approval_id → server creates a pending action and returns approval_required
2. Human approves in the web UI
3. Agent re-calls with approval_id set to the action ID

---

Tier 1 — Use (read-only + trigger)

list_flows

List all integration flows with status, health, and message counts.

Parameter	Type	Required	Description
status	string	No	Filter: draft, active, paused, error

{ "name": "list_flows", "arguments": { "status": "active" } }

search_flows

Search flows by name or description.

Parameter	Type	Required	Description
query	string	Yes	Name or description to search for

{ "name": "search_flows", "arguments": { "query": "order-webhook" } }

get_flow_status

Get detailed status of a flow including recent metrics and health.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID

{ "name": "get_flow_status", "arguments": { "flow_id": "..." } }

trigger_flow

Send a payload through a flow. Accepts UUID or flow name (resolved via search).

Parameter	Type	Required	Description
flow_id	string	Yes	Flow ID (UUID) or flow name
payload	object	Yes	JSON payload to process

{
  "name": "trigger_flow",
  "arguments": {
    "flow_id": "order-webhook-to-erp",
    "payload": { "order_id": "ORD-123", "total": 99.99 }
  }
}

list_published_apis

List available published API endpoints with their schemas.

No parameters.

call_published_api

Send data to a published API endpoint.

Parameter	Type	Required	Description
api_path	string	Yes	API path (e.g., "partner-orders")
payload	object	Yes	JSON payload

{
  "name": "call_published_api",
  "arguments": { "api_path": "partner-orders", "payload": { "order_id": "PO-001" } }
}

list_schedules

List scheduled flows with cron expression, next run, last status, and enabled state.

Parameter	Type	Required	Description
flow_id	string (uuid)	No	Filter by flow ID

get_batch_status

Get status and progress of a batch job.

Parameter	Type	Required	Description
batch_job_id	string (uuid)	Yes	Batch job ID

list_batch_jobs

List recent batch jobs with status and progress.

Parameter	Type	Required	Description
flow_id	string (uuid)	No	Filter by flow ID

list_adapters

List custom code adapters with type, test status, and AI-generated flag.

No parameters.

test_adapter

Test an adapter in a sandboxed V8 isolate with sample input.

Parameter	Type	Required	Description
adapter_id	string (uuid)	Yes	Adapter ID
input	object	Yes	Sample input payload

{
  "name": "test_adapter",
  "arguments": {
    "adapter_id": "...",
    "input": { "order_id": "ORD-123", "line_items": [{"sku": "A", "qty": 2}] }
  }
}

list_lookups

List all lookup tables for value translation in mappings.

No parameters.

get_lookup

Get a lookup table by ID with metadata and entries.

Parameter	Type	Required	Description
table_id	string (uuid)	Yes	Lookup table ID
search	string	No	Search entries by key or value
limit	number (1-100)	No	Max entries (default: 20)

export_batch_errors

Export error details for a batch job — failed records with error messages and original payloads.

Parameter	Type	Required	Description
batch_job_id	string (uuid)	Yes	Batch job ID

get_api_spec

Retrieve the OpenAPI specification for a published API endpoint.

Parameter	Type	Required	Description
api_id	string (uuid)	Yes	Published API ID
format	string	No	"json" or "yaml" (default: json)

{ "name": "get_api_spec", "arguments": { "api_id": "...", "format": "yaml" } }

get_messages

View recent message logs for a flow. Requires tier 3 permission at runtime.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID
status	string	No	Filter: received, success, failed, retrying, dead_lettered
limit	number (1-100)	No	Max messages (default: 20)

---

Tier 2 — Build (read + create)

list_catalog

List available connector types from the catalog with config schemas.

No parameters.

create_instance

Create a new connector instance. Requires approval.

Parameter	Type	Required	Description
catalog_id	string (uuid)	No	Catalog entry ID
name	string	Yes	Unique instance name
display_name	string	No	Human-readable name
config	object	Yes	Configuration with credentials
rate_limit_config	object	No	Rate limiting settings
rate_limit_config.requestsPerSecond	number	No	Max req/s
rate_limit_config.requestsPerMinute	number	No	Max req/min
rate_limit_config.dailyQuota	number	No	Max req/day
rate_limit_config.burst	number	No	Burst size
rate_limit_config.onLimit	string	Conditional	"queue", "reject", or "backoff"
approval_id	string (uuid)	No	Approval ID if pre-approved

test_instance

Test a connector instance connection.

Parameter	Type	Required	Description
instance_id	string (uuid)	Yes	Instance ID

create_flow

Generate a flow from natural language using AI, then create it. Requires approval. Tracked as AI tool for rate limiting.

Parameter	Type	Required	Description
description	string	Yes	Natural language description
source_hint	string	No	Hint about source system
target_hint	string	No	Hint about target system
approval_id	string (uuid)	No	Approval ID if pre-approved

{
  "name": "create_flow",
  "arguments": {
    "description": "Sync orders from Shopify to NetSuite whenever a new order is placed",
    "source_hint": "Shopify webhook",
    "target_hint": "NetSuite REST API"
  }
}

preview_flow

Preview how a flow transforms a sample payload without delivering.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID
sample_payload	object	Yes	Sample payload to transform

clone_flow

Clone a flow to another environment for promotion. Requires approval.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID to clone
target_environment_id	string (uuid)	Yes	Target environment ID
approval_id	string (uuid)	No	Approval ID if pre-approved

{
  "name": "clone_flow",
  "arguments": {
    "flow_id": "...",
    "target_environment_id": "..."
  }
}

deploy_flow

Deploy a draft flow — validates, compiles, activates. Requires approval. Blocked in sandbox mode.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID
approval_id	string (uuid)	No	Approval ID if pre-approved

trigger_schedule

Manually trigger a scheduled flow. Requires approval.

Parameter	Type	Required	Description
schedule_id	string (uuid)	Yes	Schedule ID
approval_id	string (uuid)	No	Approval ID

start_batch

Start a batch processing job. Requires approval.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID
records	array	Yes	Array of record objects
concurrency	number (1-50)	No	Max concurrent records (default: 5)
approval_id	string (uuid)	No	Approval ID

create_adapter

Create a custom code adapter. AI generates code from description if code is omitted. Requires approval.

Parameter	Type	Required	Description
name	string	Yes	Unique adapter name
description	string	Yes	Description / AI prompt
adapter_type	string	Yes	request_transform, response_transform, auth, enrichment, full
code	string	No	JavaScript code (AI generates if omitted)
sample_input	object	No	Sample input for testing
approval_id	string (uuid)	No	Approval ID

create_lookup

Create a new lookup table. Requires approval.

Parameter	Type	Required	Description
name	string	Yes	Kebab-case name (e.g., "country-warehouses")
description	string	No	Description
approval_id	string (uuid)	No	Approval ID

set_lookup_entry

Add or update an entry in a lookup table. Requires approval.

Parameter	Type	Required	Description
table_id	string (uuid)	Yes	Table ID
key	string	Yes	Lookup key
value	string	Yes	Lookup value
approval_id	string (uuid)	No	Approval ID

import_lookup_csv

Bulk import entries from CSV content. Requires key and value columns. Requires approval.

Parameter	Type	Required	Description
table_id	string (uuid)	Yes	Table ID
csv	string	Yes	CSV content
approval_id	string (uuid)	No	Approval ID

retry_batch_failed_records

Retry all failed records in a batch job at lower concurrency. Requires approval.

Parameter	Type	Required	Description
batch_job_id	string (uuid)	Yes	Batch job ID
approval_id	string (uuid)	No	Approval ID

create_published_api

Generate a published API endpoint from a description using AI. Requires approval.

Parameter	Type	Required	Description
description	string	Yes	API endpoint description
example_payload	object	No	Example request payload
approval_id	string (uuid)	No	Approval ID

---

Tier 3 — Manage (full access)

edit_flow

Edit an existing flow — YAML config, name, description, or status. Requires approval.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID
yaml_config	string	No	New YAML configuration
description	string	No	New description
name	string	No	New name
change_summary	string	No	Summary of changes
approval_id	string (uuid)	No	Approval ID

pause_flow

Pause an active flow — stops processing new messages.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID

resume_flow

Resume a paused flow.

Parameter	Type	Required	Description
flow_id	string (uuid)	Yes	Flow ID

retry_message

Retry delivery of a failed message.

Parameter	Type	Required	Description
message_id	string	Yes	Message ID

list_healing_events

List self-healing events, optionally filtered by flow.

Parameter	Type	Required	Description
flow_id	string (uuid)	No	Filter by flow ID

update_schedule

Update a schedule — cron expression, timezone, or enable/disable. Requires approval.

Parameter	Type	Required	Description
schedule_id	string (uuid)	Yes	Schedule ID
cron_expression	string	No	New cron (e.g., "0 9 * * 1-5")
timezone	string	No	New timezone
enabled	boolean	No	Enable or disable
approval_id	string (uuid)	No	Approval ID

update_adapter

Update an existing adapter. Requires approval.

Parameter	Type	Required	Description
adapter_id	string (uuid)	Yes	Adapter ID
name	string	No	New name
description	string	No	New description
code	string	No	New JavaScript code
adapter_type	string	No	New type
approval_id	string (uuid)	No	Approval ID

delete_lookup

Soft-delete a lookup table (entries preserved but table deactivated). Requires approval.

Parameter	Type	Required	Description
table_id	string (uuid)	Yes	Table ID
approval_id	string (uuid)	No	Approval ID

delete_lookup_entry

Remove a single entry from a lookup table. Requires approval.

Parameter	Type	Required	Description
table_id	string (uuid)	Yes	Table ID
key	string	Yes	Key to delete
approval_id	string (uuid)	No	Approval ID

approve_healing

Approve a pending self-healing fix to be applied. Requires approval.

Parameter	Type	Required	Description
healing_event_id	string (uuid)	Yes	Healing event ID
approval_id	string (uuid)	No	Approval ID

---

Cross-cutting concerns

PII filtering

Responses are filtered before returning to the agent:

• Sensitive config fields (api_key, token, password, secret, etc.) → ***REDACTED***
• PII fields (email, phone, SSN, address, etc.) → ***PII*** in message-related tools, unless pii_access is enabled

Rate limiting

• Per-second rate limit per agent key
• Daily quota per agent key
• AI tool calls (create_flow, create_published_api, create_adapter) tracked separately

Loop detection

Repeated identical calls (same tool + same arguments) from the same agent key are detected and blocked.

Audit logging

Every tool call is recorded with: agent key ID, tool name, input, output, duration, and status (success, error, denied, approval_required, loop_detected).