123 lines
5.3 KiB
Plaintext
123 lines
5.3 KiB
Plaintext
---
|
||
tags:
|
||
- MCP
|
||
- API
|
||
- AI
|
||
- Automation
|
||
---
|
||
|
||
# Model Context Protocol (MCP)
|
||
|
||
Homarr exposes a stateless [Model Context Protocol](https://modelcontextprotocol.io) server at `/api/mcp`. It maps the
|
||
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.
|
||
|
||
## Configure a client
|
||
|
||
Create an API key under **Management → Tools → API → Authentication**, then add the endpoint and header to the client's
|
||
MCP configuration:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"homarr": {
|
||
"url": "https://homarr.example.com/api/mcp",
|
||
"headers": {
|
||
"ApiKey": "<id>.<token>"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Clients without Streamable HTTP support can use `mcp-remote` over STDIO:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"homarr": {
|
||
"command": "npx",
|
||
"args": ["-y", "mcp-remote", "https://homarr.example.com/api/mcp", "--header", "ApiKey:<id>.<token>"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
The **AI / MCP** tab on Homarr's API page shows the current endpoint, configuration, and generated tool catalog. Filter
|
||
the catalog by namespace, tool name, or description; matching categories expand automatically.
|
||
|
||
## Authentication and permissions
|
||
|
||
MCP supports API keys and OAuth 2.1 with PKCE. API keys are simpler for direct client configuration; OAuth is available
|
||
for clients that support dynamic authorization.
|
||
|
||
Copy the complete generated API key, including both parts and the dot: `<id>.<token>`. Sending only the ID or token
|
||
returns `invalid_token`. Keep the full key private when sharing client configuration or diagnostics.
|
||
|
||
When Homarr is behind a reverse proxy that does not preserve the public host and protocol, set `BASE_URL` to the exact
|
||
public origin, for example `https://homarr.example.com`. Do not include a path. OAuth clients discover the authorization
|
||
server and protected resource through Homarr's `/.well-known/` routes.
|
||
|
||
Tools use the permissions of the API key owner or authorized user. Creating a key does not grant additional access.
|
||
Custom Widget and Workshop authoring tools, prompts, and resources are visible only to administrators.
|
||
|
||
Use HTTPS when the endpoint crosses an untrusted network.
|
||
|
||
## Verify the endpoint
|
||
|
||
The 2025 compatibility path accepts a compact `tools/list` request:
|
||
|
||
```sh
|
||
curl -X POST \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Accept: application/json, text/event-stream' \
|
||
-H 'ApiKey: <id>.<token>' \
|
||
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
|
||
https://homarr.example.com/api/mcp
|
||
```
|
||
|
||
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.
|
||
|
||
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`.
|
||
|
||
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
|
||
through MCP.
|
||
|
||
The built-in [Assistant](./assistant) uses the same tool catalog with the current Homarr session and asks for approval
|
||
before mutations by default.
|