feat: add MCP endpoint for sending messages

[RedwindA]

Closes #1059

Adds an optional, built-in Model Context Protocol endpoint at /mcp, so AI agents can send messages with an application token:

claude mcp add gotify --transport http https://gotify.example.com/mcp --header "Authorization: Bearer <apptoken>"

Scope

Kept tightly scoped as discussed in #1059: sending messages only, nothing else.

• Auth: application tokens only, via the existing RequireApplicationToken middleware (X-Gotify-Key, Authorization: Bearer, or ?token=). Client tokens and unknown tokens get 401, basic auth gets 403, so an agent can never read, delete or manage anything.

• One tool: send_message with message (required), title, priority, and three convenience flags mapped to documented extras:

  • markdown → client::display.contentType
  • click_url → client::notification.click.url
  • big_image_url → client::notification.bigImageUrl

  Raw extras are intentionally not exposed, so models can't make up namespaces.

• Stateless: Streamable HTTP in stateless + JSON-response mode. No sessions, no SSE, no extra server state; it behaves like any other REST endpoint behind a reverse proxy or with multiple instances.

• Shared logic: the defaulting/store/notify part of CreateMessage is extracted into createMessage, so REST and MCP behave the same (default title = app name, default priority, stream notification).

• Opt-out: GOTIFY_SERVER_MCP_ENABLED (default true). With false, /mcp is not registered at all.

Why built in rather than OpenAPI-to-MCP

• Setup: an OpenAPI-to-MCP bridge is an extra service users have to host and maintain. Most AI clients only accept an MCP URL, and remote/hosted agents can't run a local bridge at all. Here it's one line of client config.
• Better guidance than the spec: the tool schema carries hints the swagger spec doesn't, e.g. what priority ranges mean, and that click_url / big_image_url only take effect in the Android client.
• Small maintenance surface: ~115 lines in api/mcp.go, one tool, reusing the existing message path.

Dependency

Uses the official github.com/modelcontextprotocol/go-sdk (v1.x, maintained by the MCP org with Google). It adds 5 small indirect modules: google/jsonschema-go, segmentio/encoding, segmentio/asm, yosida95/uritemplate, golang.org/x/time.

Tests

Integration tests in router/mcp_test.go use the SDK client against the real router: sending with and without extras, default title/priority, empty message, token types (app/client/unknown/basic auth), and the disabled switch.

Open question

The endpoint is enabled by default, since it doesn't grant anything an application token can't already do via POST /message. Happy to flip the default to false if you prefer.

[codecov]

Codecov Report

❌ Patch coverage is 97.29730% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.62%. Comparing base (f77d8a0) to head (3ae2545).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
api/message.go	80.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1066      +/-   ##
==========================================
+ Coverage   76.12%   76.62%   +0.50%     
==========================================
  Files          67       68       +1     
  Lines        3619     3688      +69     
==========================================
+ Hits         2755     2826      +71     
+ Misses        653      652       -1     
+ Partials      211      210       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jmattheis]

Works great (:.

Prompt

Output

[RedwindA]

Thanks for testing it out, glad it works well!

I've reverted the README changes and moved the docs to gotify/website#107, as a new "AI Agents (MCP)" page under Guides.

[jmattheis]

Thanks!