lasuite-docs-mcp

MCP server for the LaSuite Docs external API.

It exposes Docs operations (list/read/create/update/delete documents, versions, favorites, current user) as MCP tools. Authentication uses the OIDC Authorization Code + PKCE flow against any OpenID Connect provider, with a refresh token cached in the OS keychain. Runs over stdio — no public hosting, no inbound ports. The OIDC redirect is captured by a one-shot loopback server on 127.0.0.1.

Claude ──stdio──> lasuite-docs-mcp ──Bearer token──> Docs /external_api/v1.0
                        │
                        └── Auth Code + PKCE ──> OIDC provider (issues + introspects tokens)

Works with any standards-compliant OIDC provider (Keycloak, Authentik, Zitadel, Auth0, Okta, Ory Hydra, …). Authentik is used as a worked example throughout, marked Example (Authentik).

1. Prerequisites

• Python ≥ 3.10

• A running LaSuite Docs instance with the resource server enabled (§2)

• An OIDC provider you control, able to register clients and run token introspection (§3)

Related MCP server: google-workspace-mcp-server

2. Configure LaSuite Docs (server side)

Docs must run as an OIDC resource server. Set in Docs' environment:

OIDC_RESOURCE_SERVER_ENABLED=True
OIDC_OP_URL=<issuer URL of your OIDC provider>
OIDC_OP_INTROSPECTION_ENDPOINT=<provider token-introspection endpoint>
OIDC_RS_CLIENT_ID=<client id Docs uses to call introspection>
OIDC_RS_CLIENT_SECRET=<that client's secret>
OIDC_RS_AUDIENCE_CLAIM=<claim Docs checks for audience, e.g. aud>
OIDC_RS_ALLOWED_AUDIENCES=<value the MCP token must carry, see §3.4>

Introspection-response format — important. django-lasuite ships two resource server backends:

Most providers (Keycloak, Authentik, Zitadel, Auth0, …) return plain JSON. If yours does, set:

OIDC_RS_BACKEND_CLASS=lasuite.oidc_resource_server.backend.ResourceServerBackend

Leave the default only if your provider actually issues JWT-secured introspection responses (e.g. ProConnect). Wrong choice → 400 Bad Request / "improperly configured" (see §9).

The EXTERNAL_API setting controls which scopes/endpoints are active. documents and users are enabled by default; document_access and document_invitation are disabled by default — enable them in EXTERNAL_API for the accesses/invitations tools.

Docs validates every token by introspecting it and checking: the token is active, its issuer equals OIDC_OP_URL, and its audience claim is in OIDC_RS_ALLOWED_AUDIENCES. All three must line up (§3). Mismatch → 400/401.

3. Configure the OIDC provider

Register a client for the MCP server and make sure the tokens it issues pass Docs' three checks. The concepts are provider-agnostic; the example shows where each lives in Authentik.

3.1 Register the MCP client

Create an OAuth2 / OIDC client for the MCP server:

• Client type: public (PKCE, no secret) — recommended for a desktop/CLI tool. Confidential (with secret) also works.

• Grant type: Authorization Code (+ refresh token).

• Redirect URI: http://127.0.0.1:8765/callback (exact match; change both here and OIDC_REDIRECT_URI together).

• Scopes: openid profile email (+ an audience scope, §3.4).

Example (Authentik) — Admin → Applications → Providers → Create → OAuth2/OpenID Provider. Set redirect URI http://127.0.0.1:8765/callback, client type Public, attach an Application. Note its issuer URL https://<host>/application/o/<app-slug>/.

3.2 Issuer must match Docs (iss check)

The token's iss claim must equal Docs' OIDC_OP_URL exactly. Easiest way: let the MCP client and Docs trust the same issuer.

• If your provider has one global issuer (Keycloak realm, Zitadel, Auth0 tenant), this is automatic — point both at it.

• If your provider issues a per-client/per-application issuer, either reuse the same provider/issuer Docs already trusts, or switch to a global/shared issuer mode so both emit the same iss.

Example (Authentik) — issuer is per-application by default (…/o/<slug>/), so a separate MCP application gets a different iss than the Docs login app → InvalidClaimError: iss. Fix: set the provider's Issuer mode = "Same identifier (global)" on both providers, or have the MCP use the same provider Docs trusts.

3.3 Introspection must accept the token (active check)

Docs introspects with OIDC_RS_CLIENT_ID/SECRET. Many providers only return active: true when the introspecting client is allowed to introspect that token (usually the token-issuing client, or one explicitly granted). If a different client introspects, you get active: false → "user is not active".

Fix: set Docs' OIDC_RS_CLIENT_ID/SECRET to a client permitted to introspect the MCP tokens — typically the same client that issues them, or configure your provider's introspection/audience permissions accordingly.

Example (Authentik) — cross-client introspection returns active:false. Set Docs OIDC_RS_CLIENT_ID/SECRET to the MCP application's client.

3.4 Audience (OIDC_RS_ALLOWED_AUDIENCES check)

The token must carry an audience value that Docs allows. Two approaches:

A — provider emits the audience claim (recommended). Add a claim/mapper so issued tokens include the configured audience under the claim Docs reads (OIDC_RS_AUDIENCE_CLAIM). Set OIDC_RS_ALLOWED_AUDIENCES to that value.

Example (Authentik) — Customisation → Property Mappings → Create → Scope Mapping: scope name docs, expression return {"docs-aud": "<your-audience>"}. Attach scope docs to the provider, add docs to OIDC_SCOPE, set Docs OIDC_RS_AUDIENCE_CLAIM=docs-aud and OIDC_RS_ALLOWED_AUDIENCES=<your-audience>. Simpler alternative: use the standard aud claim (= client id by default) — set OIDC_RS_AUDIENCE_CLAIM=aud, OIDC_RS_ALLOWED_AUDIENCES=<mcp-client-id>.

B — audience request parameter. If your provider honors an audience auth-request param, set OIDC_AUDIENCE (§4). Not all providers honor it (Authentik ignores it) — prefer A.

The claim name in OIDC_RS_AUDIENCE_CLAIM and the value in OIDC_RS_ALLOWED_AUDIENCES must point at the same thing, and that thing must be present in the token / introspection response.

4. Configure the MCP server

cp .env.example .env   # then edit, or pass these via the MCP env block (§6)

5. Install

Pick one. All expose the lasuite-docs-mcp command.

uv tool (recommended):

uv tool install git+https://github.com/Bone2510/lasuite-docs-mcp     # from GitHub
uv tool install .                                                    # local checkout

pipx:

pipx install git+https://github.com/Bone2510/lasuite-docs-mcp

Editable dev install:

python -m venv .venv && source .venv/bin/activate
pip install -e .

No install (uvx, run on demand):

uvx --from git+https://github.com/Bone2510/lasuite-docs-mcp lasuite-docs-mcp

6. Register in Claude Code

Add to your MCP config (~/.claude.json / project .mcp.json). With uv tool/pipx the command is on your PATH. The installed command runs from an arbitrary working dir, so pass config via the env block (a .env is only picked up when the cwd is the project dir):

{
  "mcpServers": {
    "lasuite-docs": {
      "command": "lasuite-docs-mcp",
      "env": {
        "DOCS_BASE_URL": "https://docs.example.org",
        "OIDC_OP_URL": "https://auth.example.org/realms/main",
        "OIDC_CLIENT_ID": "lasuite-docs-mcp",
        "OIDC_CLIENT_SECRET": "...",
        "OIDC_SCOPE": "openid profile email docs",
        "OIDC_REDIRECT_URI": "http://127.0.0.1:8765/callback"
      }
    }
  }
}

No-install variant:

"command": "uvx",
"args": ["--from", "git+https://github.com/Bone2510/lasuite-docs-mcp", "lasuite-docs-mcp"]

On the first tool call the server opens your browser to the provider. After login it captures the redirect on 127.0.0.1:8765, stores the refresh token in your OS keychain, and reuses/refreshes it silently afterward.

7. Test standalone

mcp dev lasuite_mcp/server.py     # MCP inspector (interactive)

Call get_current_user first — it exercises the whole chain (login → introspection → issuer → audience → user).

8. Available tools

get_current_user, list_documents, get_document, get_children, list_versions, list_trashbin, list_favorites, create_document, update_document, delete_document, restore_document, move_document, add_favorite, remove_favorite.

9. Troubleshooting

Server-side errors surface as a bare Django page; the real reason is in the Docs backend logs. Common cases (all server-side OIDC config):

10. Security notes

• PKCE (S256) is always used, even with a client secret.

• Redirect is loopback-only (127.0.0.1), random state checked against CSRF.

• Refresh token lives in the OS keychain (via keyring); if keyring is unavailable it falls back to in-memory (re-login each start).

• Tokens are never logged.

Notes / unknowns to verify against your instance

• Content format: Docs uses a Yjs/BlockNote CRDT editor. The content field on create/update may expect a base64 CRDT blob rather than plain text/markdown on some versions. Verify the payload shape before relying on content tools.

• Exact sub-paths (favorite-list/, move/, restore/, favorite/) follow current conventions — confirm against your Docs EXTERNAL_API routes.