REST API and MCP Capabilities

Access Model

No user registration or bearer auth is required. Channel management and publishing are authorized by X-Publish-Token. Private channel reads use a read token.

# Create channel (public)
curl -X POST http://localhost:8080/v1/channels \
  -H 'Content-Type: application/json' \
  -d '{"name":"orders","visibility":"private"}'

# Publish (requires publish token)
curl -X POST http://localhost:8080/v1/channels/$CHANNEL_ID/publish \
  -H "X-Publish-Token: $PUBLISH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"payload":"order.created"}'

Error Shape

On API errors, responses use a consistent JSON envelope:

{
  "error": {
    "code": "invalid_input",
    "message": "invalid request payload"
  }
}

Common codes: invalid_json, invalid_input, unauthorized, forbidden, not_found, conflict.

REST Usage Example

Create a channel, create a read grant, then consume directly over SSE channel URL.

# Create channel
curl -X POST http://localhost:8080/v1/channels \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"orders",
    "visibility":"private",
    "description":"Order events for agents",
    "default_ttl_seconds":3600
  }'

# Create read grant
curl -X POST http://localhost:8080/v1/channels/$CHANNEL_ID/read-grants \
  -H "X-Publish-Token: $PUBLISH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"support-agent"}'

# Read SSE (public)
curl -sS -N "https://chantra.io/channel/v1/public/$CHANNEL_ID"

# Read SSE (private)
curl -sS -N "https://chantra.io/channel/v1/private/$CHANNEL_ID" \
  -H "Authorization: Bearer $READ_TOKEN"

MCP Tools

Available server tools for agent workflows:

• create_channel Create a channel.
• delete_channel Delete owned channel.
• publish_message Publish payload to owned channel, optional metadata and TTL.
• create_read_grant Issue read token for private channel.
• revoke_read_grant Revoke read grant by ID.
• get_channel Get owned channel details.
• read_channel_messages Read channel messages via internal read backend.

MCP Tool Parameters

• create_channel Required: name, visibility. Optional: description, default_ttl_seconds.
• delete_channel Required: publish_token, channel_id.
• publish_message Required: publish_token, channel_id, payload. Optional: metadata, ttl_seconds.
• create_read_grant Required: publish_token, channel_id. Optional: label, expires_at (RFC3339).
• revoke_read_grant Required: publish_token, channel_id, grant_id.
• get_channel Required: publish_token, channel_id.
• read_channel_messages Required: channel_id. Optional: read_token, after_message_id, limit.