docs(mcp): simplify setup and troubleshooting
This commit is contained in:
1 parent
a7508eab00
commit
f41b544828
1 file changed
+3
-28
@@ -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
|
||||
|
||||
Reference in new issue
Block a user