feat(deployments): add ocis-mcp-server to the ocis_full example

[dj4oC]

Problem

Using the oCIS MCP Server (https://github.com/owncloud/ocis-mcp-server) against a local
ocis_full deployment currently requires building or downloading the server separately,
then manually configuring it to point at the running stack. There's no way to just turn
it on as part of the example the same way you'd turn on Collabora, ClamAV, or Keycloak.

Solution

Adds mcp.yml, a new optional compose fragment following the same pattern as the other
optional services in this example (tika.yml, clamav.yml, keycloak.yml, ...). It runs
the owncloud/ocis-mcp-server image with the HTTP transport, fronted by the existing
Traefik reverse proxy on a new subdomain (mcp.owncloud.test by default, same TLS handling
as every other service here).

Toggle it on with OCIS_MCP=:mcp.yml in .env. Two things must be configured before it
starts serving real tool calls:

• OCIS_MCP_HTTP_SECRET — required whenever the service is enabled; the container itself
  refuses to start without it, since the HTTP endpoint executes tools with the configured
  app token's privileges.
• OCIS_MCP_APP_TOKEN_USER / OCIS_MCP_APP_TOKEN_VALUE — an oCIS app token created with
  ocis auth-app create, exactly as documented in the upstream project's Getting Started
  guide.

Both the example's own README.md and the developer docs page
(docs/ocis/deployment/ocis_full.md) gained a new subsection describing the option,
matching the existing Keycloak / Clamav subsections.

Testing

• docker-compose config --quiet validated with the service both disabled (default) and
  enabled.
• Brought up traefik, ocis, and ocis-mcp-server in a local ocis_full stack, using an
  image built locally from the ocis-mcp-server repo's Dockerfile (see Known Limitation
  below). Confirmed an unauthenticated request to https://mcp.owncloud.test/mcp returns
  401. Created a real oCIS app token via ocis auth-app create, wired it in, and
  confirmed an authenticated MCP initialize request completes successfully end-to-end
  through Traefik (serverInfo.name: "ocis-mcp-server" in the JSON-RPC response).
• This surfaced a real gap: ocis_full's default START_ADDITIONAL_SERVICES doesn't
  include auth-app, so ocis auth-app create silently returns an empty token until
  auth-app is also enabled. Fixed by adding a prerequisite note to both docs locations
  (see the docs(deployments): note auth-app must be enabled... commit on this branch).
• No Go code changed; no go test / -race surface applies to this change.

Known Limitation

owncloud/ocis-mcp-server is not yet published to any container registry — the
ocis-mcp-server repo currently only builds and archives binaries in its release
pipeline, with no Docker build/push step. This PR's compose wiring was verified against a
locally-built image standing in for the real one. Until an owncloud/ocis-mcp-server
image is actually published, enabling OCIS_MCP=:mcp.yml will fail to pull. Publishing
that image is tracked separately and is a prerequisite for this option to work for real
users.

Risk

Low. This is an additive, off-by-default optional service — it does not change the
behavior of the default ocis_full stack for anyone who doesn't opt in.

🤖 Generated with Claude Code

[kw-security]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[mmattel]

@dj4oC
Can you pls reference the PR where all the envvars OCIS_MCP_xxx are added?
I have not found any PR for this.
Consider that new envvars need to follow the documented rules adding them.
This PR cant be merged before these envvars are part of the ocis code!

Important: if these envvars are docker only, they MUST be named differerntly. Otherwise this confuses the naming rules for envvars used in ocis. OCIS_xxx or <SERVICENAME>_xxx envvar names are ocis only.

@kobergj fyi

[dj4oC]

@dj4oC Can you pls reference the PR where all the envvars OCIS_MCP_xxx are added? I have not found any PR for this. Consider that new envvars need to follow the documented rules adding them. This PR cant be merged before these envvars are part of the ocis code!

Important: if these envvars are docker only, they MUST be named differerntly. Otherwise this confuses the naming rules for envvars used in ocis. OCIS_xxx or <SERVICENAME>_xxx envvar names are ocis only.

@kobergj fyi

owncloud/ocis-mcp-server#39

Important: if these envvars are docker only, they MUST be named differerntly. Otherwise this confuses the naming rules for envvars used in ocis. OCIS_xxx or <SERVICENAME>_xxx envvar names are ocis only.

This must be reflected in agents.md please open a PR if there is a rule to apply

[jvillafanez]

Some notes:

• I guess requiring the auth-app to be enabled is convenient, but we should try to use a different auth mechanism. Likely something to consider for the future for both the ocis-mcp-server and oCIS. A specific secure mechanism to authenticate external services might be worthy also for oCIS (not sure if OIDC supports something like this).
• Password and secrets in the environment. It should be avoided as much as possible.

I don't think we can do much about those at the moment.

In any case, I'm worried about the token expiration. Once the token expires, what are the next steps? Without any additional info, I'd guess it's switch off the service, replace the password and then switch on the service again with the new password. If this is the case, why not expiring the password much earlier (1 month or even less) at least to reduce the password exposure?

---

For the PR itself, I think it's fine.

[kobergj]

@mmattel the OCIS_MCP envvars are from a different project (ocis-mcp). Though envvar naming is not ideal from our point of view, we will and can not document external envvars. This PR is only about adding the MCP server to the ocis full example, not about discussing its functionality.

@jvillafanez what Passwords and secrets do you mean? I didn't see any defaults, envvars are empty by default. I'm strongly against using default passwords. They WILL be reused in production environments.
Regarding auth mechanism: I agree. In the future dedicated authentication method (or improving auth app) could be valuable. If you need something for testing, the MCP works flawlessly with basic-auth.

---

Looks good from my side. I don't mind adding the MCP to the ocis_full.

[dj4oC]

@kw-fscheuer may I ask for a review please whether we can ship it bundled?

[jvillafanez]

@jvillafanez what Passwords and secrets do you mean? I didn't see any defaults, envvars are empty by default. I'm strongly against using default passwords. They WILL be reused in production environments.

You'll have to write the app token in the docker-compose file. If someone gets access to the host where the file is or get access to the container, the token will get exposed; and it will likely refer to the admin (or admin-like) account.

As said, I don't think we can do much about it at the moment. Maybe we can try to use the mcp as a bridge: you use your oCIS account in the agent so it sends the credentials when interacting with the mcp. Basically, "as agent, I want the mcp to use these credentials for all the requests the agent sends to the mcp". However, this needs changes in the mcp server.

In addition, since you're kind of expected to use an admin account for the mcp server, does it means that any agent would have admin information? Do we have some safety net to prevent regular users (using agents) to access such information? I'm not entirely sure how the mcp server works.