MCP tools

Krafter exposes 37 read-only tools over the Model Context Protocol (MCP), letting AI assistants query data across services using the same API keys you already issue for REST.

Endpoint: POST https://app.krafter.dev/mcp

GET /mcp is reserved by the MCP spec but Krafter does not currently support the Server-Sent Events stream — it returns 405 Method Not Allowed.

Transport

Krafter implements JSON-RPC 2.0 over Streamable HTTP at protocol version 2025-03-26. Each request is a single JSON-RPC message; each response is a single JSON-RPC reply (or 202 for notifications). There is no persistent session.

The server identifies itself as { "name": "krafter", "version": "1.0.0" } in the initialize response.

Supported methods

Method	Description
initialize	Negotiates protocol version and returns server capabilities (tools only).
notifications/initialized	Client acknowledgement after initialize. Server replies 202 Accepted.
tools/list	Returns the tools the calling API key is authorised for.
tools/call	Invokes a tool. Tool result is returned as a JSON-encoded text content block.

Any other method returns JSON-RPC error code -32601 ("Method not found"). Malformed messages return -32600 ("Invalid request").

Tool errors

JSON-RPC code	Meaning
-32001	Tool not found
-32002	Permission denied (API key lacks the required scope)
-32602	Invalid or missing parameters
-32603	Internal error (uncaught exception during tool dispatch)

Authentication

Send an API key in the Authorization header — the same Bearer token format used by the REST API:

Authorization: Bearer kr_live_...

Authentication runs through the standard API key pipeline, so MCP requests count toward the per-team rate limit (default bucket — see rate limits) and produce an audit log entry on every call.

Scope filtering

Each tool module enforces a single <service>:read scope. tools/list only returns tools whose scope the caller's API key satisfies; tools/call re-checks the scope before dispatching.

Module	Required scope
Analytics	analytics:read
Cron	cron:read
Flags	flags:read
Forms	forms:read
Logs	logs:read
Mail	mail:read
Push	push:read
Webhooks	webhooks:read

A wildcard scope (*) grants access to every module. Any other write-level scope (mail:write, flags:write, …) does not imply read access — pair it with the matching :read scope to use the corresponding MCP tools.

Origin validation

POST /mcp validates the Origin header against :krafter, :mcp_allowed_origins (default ["http://localhost:*"]). Mismatched origins return 403 Forbidden. Configure the list in runtime.exs to allow your assistant's host.

Tool inventory

Analytics — analytics:read (7 tools)

Tool	Description
analytics_list_sites	List all analytics sites for your team.
analytics_get_stats	Pageviews, visitors, visits over a period with optional dimension breakdown.
analytics_realtime	Active visitors in the last 30 minutes.
analytics_top_pages	Most visited pages for a period.
analytics_top_referrers	Top traffic sources for a period.
analytics_events	Custom event counts and revenue.
analytics_goal_conversions	Conversion stats for a specific goal.

Cron — cron:read (3 tools)

Tool	Description
cron_list_jobs	All cron jobs for your team with schedules and last-run info.
cron_get_job	Details for a single cron job by ID.
cron_list_executions	Recent executions for a specific job.

Flags — flags:read (5 tools)

Tool	Description
flags_list_projects	All feature-flag projects for your team.
flags_list_flags	Flags in a project, optionally filtered by status and tags.
flags_get_flag	A single flag by ID, including its evaluation rules.
flags_list_audit_log	Audit log entries for your team's flags.
flags_list_experiments	A/B test experiments for a specific flag.

Forms — forms:read (3 tools)

Tool	Description
forms_list_forms	All forms for your team with submission and unread counts.
forms_get_form	Details for a single form by ID.
forms_list_submissions	Submissions for a form, with spam-status filter and full-text search.

Logs — logs:read (5 tools)

Tool	Description
logs_list_projects	All log projects with retention and daily-limit settings.
logs_search	Search entries by level, stream, full-text query, and time range (max 1000).
logs_list_streams	All streams within a project.
logs_list_alerts	Alerts configured for a project.
logs_get_usage	Today's ingestion usage (entry count + bytes).

Mail — mail:read (5 tools)

Tool	Description
mail_list_emails	Emails sent by your team, with status filter and search.
mail_get_email	A single email record with its delivery events.
mail_email_stats	Totals by status, with optional daily breakdown.
mail_list_domains	Sending domains and their verification status.
mail_list_suppressions	Suppressed addresses (bounces, complaints, manual).

Push — push:read (5 tools)

Tool	Description
push_list_apps	Push apps with subscriber counts.
push_list_subscribers	Subscribers for an app, filtered by platform / status / tags.
push_list_notifications	Notifications for an app, optionally filtered by status.
push_get_notification	A single notification with targeting and delivery stats.
push_daily_stats	Daily counters for an app (sent, delivered, clicked, failed, new_subscribers, unsubscribes). The delivered counter is currently always 0 — see Analytics → Response Fields for why.

Webhooks — webhooks:read (4 tools)

Tool	Description
webhooks_list_sources	Webhook sources for your team.
webhooks_get_source	Details for a source including destination count.
webhooks_list_events	Received events for a source, with event_type filter.
webhooks_list_destinations	Forwarding destinations for a source.

Coverage gaps

The AI Audit service is not yet exposed via MCP. Findings, scans, tasks, and reports must be queried through the REST API at /api/v1/audit/*. There is no audit:read-scoped MCP module.

Write actions across all services (creating emails, toggling flags, scheduling notifications, etc.) are also outside the MCP surface today — MCP is read-only by design.