docs(mcp): simplify setup and troubleshooting

This commit is contained in:
ajnart committed 2026-09-10 19:16:36 +02:00
1 parent a7508eab00
commit f41b544828
1 file changed
+3 -28
+3 -28
View File
@@ -16,9 +16,7 @@ current Homarr API to tools for compatible AI clients.
The endpoint implements MCP `2026-07-28` and accepts 2025 Streamable HTTP clients through a compatibility path. The old
`/api/mcp/mcp` route remains as an alias; use `/api/mcp` for new clients.
Each HTTP request authenticates independently and uses a fresh MCP server instance. Neither protocol path requires an
MCP session ID or server affinity. Homarr still checks the authenticated user’s permissions for every tool call;
stateless MCP does not remove authentication or the storage used by OAuth authorization flows.
Requests authenticate independently; no MCP session ID or server affinity is required.
## Configure a client
@@ -86,37 +84,14 @@ curl -X POST \
The removed HTTP+SSE `/sse` and `/message` transports return `410 Gone`.
Successful `server/discover` or `initialize` responses confirm connectivity, but do not validate the tool catalog.
Use `tools/list` above to check that the client can discover tools. If it returns
`Date cannot be represented in JSON Schema`, the server failed to generate a tool schema; changing the API key will
not resolve that error. Update Homarr to a release containing the invitation date schema fix.
## Tools and resources
The generated catalog includes available board, app, integration, Docker, Kubernetes, media, DNS, download, and other
Homarr procedures. Queries are read-only; mutations change state. The exact catalog depends on the release and current
user permissions, so inspect `tools/list` or the table in Homarr instead of relying on a static list.
If a tool cannot be represented by a valid JSON input schema, Homarr omits it while keeping the rest of the catalog
available. Duplicate tool names are also omitted rather than replacing one another. The Assistant uses the same
filtered catalog. Check server logs for `MCP tool omitted from catalog`, which includes the tool name, procedure path,
and one of these reasons:
- `unsupported_input`: the procedure does not declare supported object inputs or a no-input schema.
- `invalid_schema`: input schema conversion or JSON Schema validation failed.
- `duplicate_name`: multiple enabled procedures resolve to the same tool name.
- `invalid_name`: the tool name does not meet MCP naming requirements.
Diagnostics are logged once when each server process builds its catalog. They describe server-side tool definitions;
changing credentials will not repair them. Report the diagnostic and Homarr version without including API keys.
Catalog validation in CI rejects these diagnostics before release.
Tool calls preserve raw JSON arguments until tRPC validates and normalizes them. String constraints that depend on
trimming or case normalization are enforced by tRPC after normalization. ISO timestamps use the declared input
pattern, including minute precision when supported.
The `invite_createInvite` tool accepts `expirationDate` as an ISO 8601 timestamp with a timezone, such as
`2026-12-01T18:00:00Z` or `2026-12-01T19:00:00+01:00`.
Invalid schemas and duplicate tool names are omitted from both MCP and the Assistant. For missing tools, check server
logs for `MCP tool omitted from catalog` and report the diagnostic with your Homarr version. Never include API keys.
For Custom Widgets, install the official skill and follow the preview-and-evidence workflow described in
[Connect an agent](./custom-widgets/agent-authoring). Secret values are configured in Homarr and are never returned