MCP Bridge

Squawk exposes a streamable HTTP MCP endpoint at /api/mcp.

This bridge is designed for a rapid scratchpad workflow where drafting happens in external tools and final approval/push happens through Squawk.

Source of truth

• Squawk remains the canonical state for content drafts, review state, and push status.
• GitHub and downstream channels are projection targets (not the primary editing datastore).

Authentication

MCP requests require:

• Authorization: Bearer <mcp_token>
• x-organization-id: <organization_id>

Tokens are organization-scoped and include scopes:

• content.read
• content.write
• content.approve
• content.push
• content.publish

Use the organizations API to create, list, and revoke tokens.

MCP tools

The current MCP server exposes these tools:

• list_review_queue
• get_content_item
• upsert_document_draft
• update_post_draft
• create_media_upload_url
• create_media_record
• list_experts
• list_products
• approve_content_item
• push_content_item
• approve_and_push_one
• get_sync_status

push_content_item and approve_and_push_one support optional downstream targets:

• publishCms - attempt direct CMS publish after repo sync
• publishSocial - queue linked document posts for social publish
• publishNow - queue social publish for immediate processing
• scheduledFor - queue social publish for a specific datetime

Recommended one-at-a-time workflow

1. upsert_document_draft
2. list_review_queue
3. approve_and_push_one
4. get_sync_status

Uploading media assets

For image assets used by ingested documents:

1. create_media_upload_url
2. Upload bytes directly to the signed URL
3. create_media_record
4. Pass media IDs via upsert_document_draft.assetMediaIds

This keeps approval explicit and supports controlled promotion to GitHub.