MCP Reference

FrameWorks exposes an MCP (Model Context Protocol) server for AI agent integration. Connect your AI tools to create streams, manage recordings, check billing, and query analytics.

What is MCP?

MCP is an open protocol for connecting AI models to external systems. It defines three primitives: Resources (data to read), Tools (actions to take), and Prompts (guided workflows). See modelcontextprotocol.io.

Endpoint

https://bridge.frameworks.network/mcp

Discovery metadata: /.well-known/mcp.json

Tenant MCP, not cluster administration

This Bridge endpoint is a tenant-facing API surface. It does not expose platform lifecycle operations such as cluster provision, cluster release, cluster migrate, or cluster control-plane. Those operations require local GitOps manifests, SOPS material, SSH access, and platform-operator authority, so they remain in the local frameworks CLI. Use frameworks commands --output json for machine-readable CLI discovery. Any future operator MCP should be a separate, local trust boundary.

Connecting Your AI Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "frameworks": {
      "url": "https://bridge.frameworks.network/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code CLI

claude mcp add frameworks https://bridge.frameworks.network/mcp

Other Clients

Any MCP-compatible client can connect using the endpoint URL and authentication headers. See Wallet Auth for headless agent auth or use a bearer token.

Scoped access and risk controls

Interactive JWT and wallet sessions use the signed-in user’s platform role. API tokens are narrower: each tool requires its exact published domain permission, such as streams:read, streams:write, billing:read, billing:write, analytics:read, or infrastructure:write. Account, support, developer, consultant, and wallet-management tools use the corresponding account:*, support:read, developer:*, consultant:use, security:*, and placement:read/placement:write scopes.

High-risk tools require API tokens to carry both their domain scope and mcp:high-risk. Grant this only to autonomous agents that are intentionally allowed to perform destructive, credential-changing, financially costly, or arbitrary-query operations. Tool-specific confirmation fields and normal downstream authorization checks still apply.

Public operations need no credential. If an API token is supplied, its scopes still apply so a tenant-enriched version of a public response cannot bypass the token’s least-privilege boundary.

The server filters tool and resource discovery to data callable by the current credential. Resource reads require their matching domain read scope and unknown resources fail closed. Tool annotations describe read-only, destructive, idempotent, and open-world behavior for clients, but the Gateway’s server-side policy is authoritative.

The historical coarse values read and write are not wildcards and new tokens reject them. Rotate tokens to exact scopes. In particular, retention tools now use billing:read or billing:write, and both set_preferred_cluster and update_tenant_settings use settings:write; tokens created with their former stream or infrastructure scopes must be rotated. Omitting permissions creates a read-only token with streams:read.

Input objects reject unknown fields and publish constrained values as machine-readable enums. Requests are capped at 256 KiB, stateful sessions expire after 30 minutes, and tool results or resource reads above 64 KiB return RESULT_TOO_LARGE instead of malformed, truncated, or unbounded content.

Resources

Read-only data sources for account, billing, streams, analytics, infrastructure, support, and API discovery.

URI	Description
account://status	Account status, blockers, and capabilities
billing://balance	Prepaid balance, drain rate, estimated hours left
billing://pricing	Canonical meter catalog and effective tier rules
billing://transactions	Recent balance transactions
billing://invoices	Recent draft and permanent itemized invoices
billing://invoices/{invoice_id}	Itemized invoice; finalized lines are immutable
billing://payments	Recent invoice payments and outstanding balance
billing://payments/{payment_id}	One tenant-owned invoice payment and confirmation state
billing://documents	Retained invoices, receipts, and credit-note metadata
billing://documents/{kind}/{document_id}	Printable tenant-owned document with integrity hash
streams://list	List all streams
streams://{id}	Stream details (relay ID or stream_id)
streams://{id}/health	Stream health metrics
vod://list	List all VOD assets
vod://{artifact_hash}	VOD asset details (relay ID or artifact hash)
analytics://usage	Purser-rated current-period itemized usage
analytics://viewers	Viewer metrics (last 24h)
analytics://geographic	Geographic viewer distribution
analytics://routing	Routing efficiency and cross-cluster traffic
analytics://federation	Federation operations summary
analytics://network-topology	Cluster topology and peer connectivity
nodes://list	Infrastructure nodes
nodes://{id}	Node details
clusters://list	Subscribed clusters
clusters://{id}	Cluster details (capacity, pricing, status)
clusters://marketplace	Available clusters for subscription
support://conversations	Support conversation list
support://conversations/{conversation_id}	Support conversation details
knowledge://sources	Curated documentation sources for video streaming
schema://catalog	Curated GraphQL catalog (schema + templates)

Public resources (no auth required): account://status, billing://pricing, clusters://marketplace.

account://status

Always read this first. Returns:

{
  "account_ready": true,
  "rated_work_ready": true,
  "next_actions": [],
  "blockers": [],
  "capabilities": {
    "create_stream": true,
    "create_clip": true,
    "read_analytics": true
  },
  "billing": {
    "model": "prepaid",
    "balance_cents": 5000,
    "reserved_balance_cents": 1200,
    "available_balance_cents": 3800,
    "details_complete": true,
    "low_balance_warning": false,
    "drain_rate_cents_per_hour": 12
  },
  "rate_limits": {
    "requests_per_minute": 120
  }
}

account_ready means authentication and control-plane onboarding are usable. rated_work_ready and blockers describe rated media/compute work; zero balance does not make the account broken. balance_cents is the settled balance, reserved_balance_cents is already committed to active usage, and available_balance_cents is what remains spendable. Billable tool preflights use the available balance.

Billing and usage resources

billing://pricing returns every active canonical meter, including meters that have no rule on the current tier. configured: false means the tier has no rule; it does not claim that a marketplace or custom cluster can never price the meter. Configured rules retain their model, included quantity, physical unit, allowed dimensions, and complete dimension-selector configuration.

analytics://usage is a Purser-rated current-period view, not a dashboard rollup. Its line_items include zero-priced meters and preserve the unit, bounded dimensions, pricing source, and work-cluster attribution. Use billing://invoices for recent drafts and finalized invoices and billing://invoices/{invoice_id} for one itemized invoice. Draft lines remain a current preview; finalized lines are the immutable snapshot used by payment, email, and operator settlement.

Tools

Actions the agent can perform.

Tool	Description	Requires
get_media_placement_policy	Read saved/effective policy and rollout	Auth + placement:read
get_media_placement_options	Page through authorized placement selectors	Auth + placement:read
preview_media_placement	Preview saved or draft routing; not a reservation	Auth + placement:read
review_media_placement_change	Review exact policy updates without applying	Owner/Admin + placement:write
apply_media_placement_change	Apply a reviewed, idempotent policy change	Owner/Admin + placement:write; API tokens also need mcp:high-risk
get_media_placement_change	Recover a change with its original idempotency key	Auth + placement:read
get_cluster_media_consent	Read cluster-owner media consent	Auth + placement:read + cluster ownership
review_cluster_media_consent_change	Review owner consent without applying	Owner/Admin + placement:write + cluster ownership
apply_cluster_media_consent_change	Apply reviewed, idempotent owner consent	Owner/Admin + placement:write + cluster ownership; API tokens also need mcp:high-risk
get_cluster_media_consent_change	Recover an owner-consent change	Auth + placement:read + cluster ownership
request_wallet_challenge	Request a single-use EIP-191 login/link challenge	None
list_linked_wallets	List wallets linked to the authenticated user	Auth
link_wallet	Link a wallet using a fresh signed challenge	Auth
unlink_wallet	Unlink a wallet while retaining a sign-in method	Auth
link_email	Add email/password and send verification	Auth
activate_free_tier	Activate Free after email verification	Auth
get_tenant_settings	Read tenant identity and routing settings	Auth
update_tenant_settings	Update tenant name, primary cluster, or model	Owner/Admin
update_billing_details	Set billing address	Auth
get_payment_options	Get tenant-bound x402 payment options	Auth
submit_payment	Submit an x402 top-up payment	Auth
topup_balance	Request ETH or USDC deposit address (locked rate)	Auth
check_topup	Check crypto payment status	Auth
pay_invoice	Create or resume an invoice payment	Auth + Billing
start_postpaid_setup	Start Stripe or Mollie hosted postpaid setup	Auth + Billing
complete_mollie_postpaid_setup	Verify mandate and activate Mollie postpaid	Auth + Billing
create_stream	Create a push or pull stream	Auth
update_stream	Update stream settings or pull-source config	Auth
delete_stream	Delete a stream	Auth + Confirm
list_stream_keys	List push-stream ingest keys	Auth
create_stream_key	Create an additional push-stream ingest key	Auth + Confirm
delete_stream_key	Deactivate a push-stream ingest key	Auth + Confirm
refresh_stream_key	Rotate a push stream’s primary key	Auth + Confirm
validate_stream_key	Validate an ingest key	Auth
list_push_targets	List masked multistream destinations	Auth
create_push_target	Add a multistream destination	Auth
update_push_target	Update or enable a multistream destination	Auth
delete_push_target	Delete a multistream destination	Auth
create_clip	Create clip from stream	Auth + Balance
delete_clip	Delete a clip	Auth
start_dvr	Start DVR recording	Auth + Balance
stop_dvr	Stop DVR recording	Auth
delete_dvr	Delete a DVR recording and stored media	Auth + Confirm
get_retention_policy	Read tenant media-retention defaults and bounds	Auth
set_retention_policy	Set tenant media-retention defaults	Owner/Admin + Billing
set_stream_retention_overrides	Set DVR/clip retention overrides for a stream	Owner/Admin + Billing
update_asset_retention	Override retention for DVR, clip, or VOD	Owner/Admin + Billing
reset_asset_retention	Reset asset retention to the cascade default	Owner/Admin + Billing + Confirm
create_vod_upload	Start a VOD upload	Auth + Balance
get_vod_upload_status	Inspect uploaded and missing VOD parts	Auth
complete_vod_upload	Finalize a VOD upload	Auth + Balance
abort_vod_upload	Cancel an upload	Auth
delete_vod_asset	Delete a VOD asset	Auth + Confirm
resolve_playback_endpoint	Get viewer playback URLs	None
list_signing_keys	List playback signing keys	Auth
create_signing_key	Create a one-shot ES256 private key	Auth + Confirm
revoke_signing_key	Revoke a playback signing key	Auth + Confirm
set_playback_policy	Set JWT or webhook playback policy	Auth + Confirm
clear_playback_policy	Clear playback policy	Auth + Confirm
test_playback_access	Test JWT/webhook playback policy behavior	Auth
diagnose_rebuffering	Analyze rebuffering events	Auth
diagnose_buffer_health	Analyze buffer health and dry events	Auth
diagnose_packet_loss	Analyze packet loss (protocol-aware)	Auth
diagnose_routing	Analyze CDN routing decisions	Auth
get_stream_health_summary	Aggregated stream health metrics	Auth
get_anomaly_report	Detect anomalies vs baseline	Auth
list_support_conversations	List recent support conversations	Auth
search_support_history	Search support conversations	Auth
introspect_schema	Explore the GraphQL schema	Auth
generate_query	Generate a GraphQL query from templates	Auth
execute_query	Execute a GraphQL query	Auth + Balance
ask_consultant	Full Skipper pipeline with confidence tagging	Auth + Balance
browse_marketplace	Browse available infrastructure clusters	None
subscribe_to_cluster	Subscribe to a cluster	Owner/Admin + Infrastructure
unsubscribe_from_cluster	Remove a cluster subscription	Owner/Admin + Infrastructure + Confirm
create_cluster_invite	Invite a tenant to subscribe to an owned cluster	Owner/Admin + Infrastructure
revoke_cluster_invite	Revoke an outstanding cluster invite	Owner/Admin + Infrastructure
accept_cluster_invite	Redeem a cluster invite	Owner/Admin + Infrastructure
request_cluster_subscription	Request access to a cluster	Owner/Admin + Infrastructure
approve_subscription_request	Approve a pending cluster subscription	Owner/Admin + Infrastructure
reject_subscription_request	Reject a pending cluster subscription	Owner/Admin + Infrastructure
set_preferred_cluster	Set preferred cluster for DNS steering	Owner/Admin + Settings
update_cluster_marketplace	Update cluster visibility, approval, or pricing	Owner/Admin + Infrastructure + Confirm
create_enrollment_token	Create an enrollment token for edge bootstrap	Owner/Admin + Infrastructure
get_node_info	Fetch node details	Owner/Admin + Infrastructure
manage_node	Activate/deactivate/drain/restart a node	Owner/Admin + Infrastructure
set_node_mode	Set node mode (normal/draining/maintenance)	Owner/Admin + Infrastructure
get_node_health	Node health and metrics summary	Owner/Admin + Infrastructure
list_incidents	Incidents on clusters the tenant owns	Owner/Admin + Infrastructure
get_incident	One incident with alerts and timeline	Owner/Admin + Infrastructure
acknowledge_incident	Acknowledge a firing incident	Owner/Admin + Infrastructure
assign_incident	Assign an incident to yourself, or unassign it	Owner/Admin + Infrastructure
resolve_incident	Resolve an incident manually	Owner/Admin + Infrastructure
add_incident_note	Add a note to an incident timeline	Owner/Admin + Infrastructure
create_edge_cluster	Create edge cluster (returns token and Foghorn)	Owner/Admin + Infrastructure

CLI Alternative

For operators who prefer the CLI over MCP, frameworks edge deploy combines create_edge_cluster and create_enrollment_token into a single command that also provisions the edge node. See the CLI Reference and Connecting Your Edge for details.

Public tools (no auth required): request_wallet_challenge, resolve_playback_endpoint, browse_marketplace. Payment options and submission require an authenticated tenant; x402 is a top-up mechanism, never an authentication bypass.

QoE tool responses use a consistent status enum: healthy | warning | critical | no_data.

Tool Parameters

update_billing_details

• address_line1 (required): Street address
• city (required): City
• postal_code (required): Postal/ZIP code
• country (required): ISO 3166-1 alpha-2 code
• email, company, vat_number, address_line2: Optional

update_tenant_settings

• name: Tenant display name.
• primary_cluster_id: Preferred primary cluster for ingest and routing decisions.
• deployment_model: Deployment model, for example shared, dedicated, or self_hosted.

Agents can call request_wallet_challenge without authentication, sign the returned message verbatim, and reconnect once with the X-Wallet-* headers. That exchange auto-provisions a new prepaid tenant when needed and returns X-Access-Token; use the token for subsequent calls. Authenticated agents can use list_linked_wallets, link_wallet, unlink_wallet, and link_email at zero balance. After the email link is verified, activate_free_tier switches prepaid to Free without billing details or provider collection; retained prepaid funds stay as account credit. An account cannot unlink its final wallet until it has another wallet or a verified password sign-in method. x402 only tops up the resulting tenant; it is never a login credential.

link_email / activate_free_tier

• link_email takes email and password, then sends the normal verification message.
• Follow that message once; verification is required before activation.
• activate_free_tier takes no fields and selects the active canonical Free tier.
• Free produces an itemized monthly EUR 0 usage statement and needs neither a billing profile nor Stripe/Mollie.

topup_balance

• amount_cents (required): Target credit amount in tenant currency cents (USD or EUR)
• asset: USDC (default) or ETH. LPT is reserved but currently rejected (no Chainlink LPT/USD feed).

Response is a locked-rate quote: token_amount (send exactly this much), price_usd (locked at issue time via Chainlink for ETH; 1:1 for USDC), quote_source (chainlink or one_to_one), network (defaults to Arbitrum), and an expires_at 24h out. The balance credit at confirmation is received × locked_price, so you get exactly the quoted amount regardless of price drift inside the TTL.

check_topup returns status of pending | confirming | completed | expired, plus tx_hash, confirmations, and on completion credited_cents / credited_currency (USD or EUR per the account).

pay_invoice

• invoice_id (required): Invoice id from billing://invoices.
• method (required): card, crypto_usdc, or crypto_eth.
• return_url: Optional web application URL for card-checkout return.

The tool charges only the invoice’s current outstanding balance. Repeating the same call resumes its pending checkout or crypto quote. A different method is rejected until the pending payment expires or fails. Read billing://payments to inspect recent attempts and confirmation state.

start_postpaid_setup

• provider (required): stripe or mollie; it must appear in the account’s configured setup providers.
• tier_id (required): An eligible paid tier.
• Stripe: provide success_url, cancel_url, and optionally billing_period: monthly | yearly.
• Mollie: provide return_url and optionally method: creditcard | ideal | bancontact.

The tool returns a durable setup identifier and hosted action_url. Opening or returning from that URL is not proof of activation; provider confirmation is authoritative. Stripe completes from its webhook. After a successful Mollie first payment, call complete_mollie_postpaid_setup with the same tier_id; it fetches and validates the tenant’s mandate before creating the subscription.

create_stream

• name (required): Stream display name
• description, record, public: Optional
• ingest_mode: push (default) or pull
• pull_source: { source_uri, enabled }, required for pull
• source_location: Optional { mode: any | restricted, clusters: [{ cluster_id, node_ids }], avoid_node_ids }. Omitted means any; private (LAN) and multicast pull sources require restricted with clusters that allow private pull sources. Node IDs are accepted only for clusters the tenant owns. The result returns the stream’s source_location, with mode custom when its placement rules hold more than a location. update_stream takes the same field; omitting it keeps the current location. See Pull-input streams.

create_clip

• stream_id (required): Stream to clip from
• title (required): Clip title
• description, start_sec, duration_sec: Optional

resolve_playback_endpoint

• content_id (required): playback_id, stream_id, or Relay ID
• viewer_ip: Optional geo-routing hint
• Returns thumbnail preview URLs in thumbnail_assets when poster and sprite assets are available.

create_vod_upload

• filename (required): Original filename
• size_bytes (required): File size in bytes
• content_type, title, description: Optional

complete_vod_upload

• upload_id (required): Upload session ID
• parts (required): Array of { part_number, etag }

abort_vod_upload

• upload_id (required): Upload session ID

delete_vod_asset

• artifact_hash (required): VOD relay ID or artifact hash

introspect_schema

• focus (required): query, mutation, subscription, or a specific type name
• depth: Recursion depth 1-4 (default 2)

generate_query

• field_name or field_path (one required): Field name or dot-separated path (e.g., streamsConnection, analytics.usage.streaming.viewerHoursHourlyConnection)
• operation_type: query, mutation, or subscription (default query)

execute_query

• query (required): GraphQL query or mutation to execute
• variables: Variables for the query

ask_consultant

• question (required): Question for the AI video streaming consultant
• mode: Set to docs for docs-site read-only mode. Omit for regular consultant mode; MCP ask_consultant still blocks mutation tools, so call dedicated MCP tools directly when you intend to change platform state.

Returns a structured response with answer, confidence (verified, sourced, best_guess, or unknown), sources, and tools_used. This runs the configured Skipper pipeline — knowledge retrieval, optional web search, optional query rewriting/HyDE, and multi-step reasoning.

Preflight Errors

Rated tools check prepaid balance before executing; read, configuration, cleanup, and payment-recovery tools do not. Exactly €100 may use a simplified crypto document. Payments over €100, and any VAT-number claim, require the full billing fields returned by the payment blocker. See Payments — Preflight Errors for details.

Prompts

Guided workflows for common tasks.

Prompt	Description	Arguments
onboarding	Walk through account setup	None
create_live_stream	Guide to create and start streaming	stream_name (optional)
troubleshoot_stream	Diagnose stream issues	stream_id (required)
optimize_costs	Analyze usage, suggest savings	None
capabilities	Explain platform features	None
video_consultant	Expert streaming consultant persona	None
diagnose_quality_issue	Guided QoE troubleshooting workflow	stream_id (required), symptom (optional)
api_integration_assistant	Guided API integration workflow	goal (optional)
agent_instructions	Full MCP usage guide for agents	None
self_hosting	Self-hosted edge deployment guide	None

Video Consultant

The MCP server includes Skipper, an expert-level video streaming consultant. Use the video_consultant prompt to activate this mode, which guides your AI through available tools and knowledge sources.

Use ask_consultant for authenticated knowledge lookups with confidence tagging, or the diagnostic tools below for stream-level troubleshooting.

Knowledge Sources

Read knowledge://sources to get curated entry points for video streaming documentation:

{
  "sources": [
    { "name": "FrameWorks Docs", "index": "https://logbook.frameworks.network/", "sitemap": "..." },
    { "name": "MistServer Docs", "index": "https://docs.mistserver.org/", "sitemap": "..." },
    { "name": "FFmpeg Wiki", "index": "https://trac.ffmpeg.org/wiki/TitleIndex" },
    { "name": "OBS Wiki", "index": "https://obsproject.com/wiki/" }
  ]
}

Your AI can navigate these sitemaps to find codec guides, protocol references, and troubleshooting steps.

Skipper’s full knowledge base also includes SRT (Haivision), HLS (RFC 8216), nginx-rtmp, and ecosystem sources (Livepeer, WebRTC, DASH). Use ask_consultant to query the full knowledge base with confidence tagging and source citations. See the Skipper operator guide for the complete source list and how to add custom sources.

Diagnostic Tools

Tool	Use Case
diagnose_rebuffering	Viewers experiencing buffering/stuttering
diagnose_buffer_health	Quality fluctuations, dry buffer events
diagnose_packet_loss	Protocol-aware packet loss analysis
diagnose_routing	CDN path issues, geographic performance
get_stream_health_summary	Overall stream quality assessment
get_anomaly_report	Detect sudden changes from baseline

Each tool returns structured results with status, metrics, analysis, and recommendations:

{
  "status": "warning",
  "metrics": { "rebuffer_count": 47, "avg_rebuffer_duration_ms": 2340 },
  "analysis": "Elevated rebuffering. 47 events in 1h indicates upstream issues.",
  "recommendations": [
    "Reduce encoder bitrate from 6.2 Mbps to 4.5 Mbps",
    "Check upload connection stability"
  ]
}

Support History

Access past support conversations to find previous solutions:

• support://conversations — List all conversations
• support://conversations/{id} — Full conversation with messages
• search_support_history(query) — Search by keyword

Example Workflow

1. User reports: “My stream keeps buffering”
2. AI reads account://status and streams://{id}/health
3. AI calls diagnose_rebuffering and diagnose_buffer_health
4. AI searches search_support_history("buffering") for similar past issues
5. AI calls ask_consultant("rebuffering troubleshooting") for relevant documentation
6. AI provides root cause analysis and encoder recommendations