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

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.

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	Current pricing rates
billing://transactions	Recent balance transactions
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	Current billing period 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,
  "blockers": [],
  "capabilities": {
    "create_stream": true,
    "create_clip": true,
    "read_analytics": true
  },
  "billing": {
    "model": "prepaid",
    "balance_cents": 5000,
    "details_complete": true,
    "low_balance_warning": false,
    "drain_rate_cents_per_hour": 12
  },
  "rate_limits": {
    "requests_per_minute": 120
  }
}

If blockers is non-empty, resolve them before billable operations.

Tools

Actions the agent can perform.

Tool	Description	Requires
get_tenant_settings	Read tenant identity and routing settings	Auth
update_tenant_settings	Update tenant name, primary cluster, or model	Auth
update_billing_details	Set billing address	Auth
get_payment_options	Get x402 payment options	None
submit_payment	Submit an x402 top-up payment	None
topup_balance	Request ETH or USDC deposit address (locked rate)	Auth
check_topup	Check crypto payment status	Auth
create_stream	Create a push or pull stream	Auth + Balance
update_stream	Update stream settings or pull-source config	Auth + Balance
delete_stream	Delete a stream	Auth + Balance
list_stream_keys	List stream ingest keys	Auth
create_stream_key	Create an additional ingest key	Auth + Confirm
delete_stream_key	Deactivate an ingest key	Auth + Confirm
refresh_stream_key	Rotate the primary stream key	Auth + Confirm
validate_stream_key	Validate an ingest key	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	Auth + Balance
update_asset_retention	Override retention for DVR, clip, or VOD	Auth + Balance
reset_asset_retention	Reset asset retention to the cascade default	Auth + Balance
create_vod_upload	Start a VOD upload	Auth + Balance
complete_vod_upload	Finalize a VOD upload	Auth + Balance
abort_vod_upload	Cancel an upload	Auth
delete_vod_asset	Delete a VOD asset	Auth + Balance
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
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
ask_consultant	Full Skipper pipeline with confidence tagging	Auth
browse_marketplace	Browse available infrastructure clusters	None
subscribe_to_cluster	Subscribe to a cluster	Auth
unsubscribe_from_cluster	Remove a cluster subscription	Auth + Confirm
set_preferred_cluster	Set preferred cluster for DNS steering	Auth
update_cluster_marketplace	Update cluster visibility, approval, or pricing	Auth + Confirm
create_enrollment_token	Create an enrollment token for edge bootstrap	Auth
get_node_info	Fetch node details	Auth
manage_node	Activate/deactivate/drain/restart a node	Auth
set_node_mode	Set node mode (normal/draining/maintenance)	Auth
get_node_health	Node health and metrics summary	Auth
create_edge_cluster	Create edge cluster (returns token and Foghorn)	Auth

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): get_payment_options, submit_payment, resolve_playback_endpoint, browse_marketplace.

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 create wallet-provisioned tenants with x402 auth and then use this tool to finish account identity and routing setup without switching to the dashboard.

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).

create_stream

• name (required): Stream display name
• description, record, public: Optional

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

Positive-balance tools check prepaid balance before executing. Account status can also surface setup blockers, and x402 payments of €100 or more require billing details. 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