Powered by Zoomin Software. For more details please contactZoomin

MarkLogic MCP Server

Table of Contents

Authorization header behavior

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
Print
  • Last Updated: September 9, 2026
  • 2 minute read
    • Documentation

The MarkLogic MCP server handles incoming authorization headers. These headers are used when the server calls MarkLogic.

The server supports three auth modes, configured by the auth_method property under workflow context definitions in config.yaml:

Mode Incoming header expected from MCP client MarkLogic REST app server auth behavior
basic Authorization: Bearer <base64(username:password)> Decodes the credentials and uses them to authenticate to MarkLogic
digest Authorization: Bearer <base64(username:password)> Decodes the credentials and uses them to authenticate to MarkLogic
oauth Authorization: Bearer <token> Forwards the bearer token to MarkLogic REST app server on each request

In this project, “OAuth” means the IdP-backed bearer-token flow used by the oauth auth mode.

Basic and Digest

When auth_method in config.yaml is basic or digest, the MCP client must send an Authorization header in this format:

Authorization: Bearer <base64(username:password)>

The server decodes the bearer value into username:password and uses those credentials when it authenticates to MarkLogic. This keeps credential handling on the client side while still allowing the MCP server to manage the upstream MarkLogic session.

IdP / Bearer Token Flow

When auth_method in config.yaml is oauth, the MCP client must send an Authorization header in this format:

Authorization: Bearer <access-token>

The server forwards that token to MarkLogic REST app server as a Bearer token on every upstream request. This is a per-request flow: each call is evaluated with the caller’s token.

If no bearer token is present, the client is redirected to the IdP authorization endpoint instead of calling MarkLogic REST app server directly.

Failure Modes

Situation Behavior
Missing Bearer token in basic/digest mode The request fails before calling MarkLogic
Bearer token in basic/digest mode cannot be decoded as base64 username:password The request fails before calling MarkLogic
Expired or invalid bearer token in oauth mode MarkLogic Server returns an auth error, which is surfaced to the caller
MarkLogic Server credentials derived from basic/digest are invalid Upstream requests fail with an auth error

Practical Notes

  • The server reads the Authorization header from the incoming MCP request using a case-insensitive lookup.
  • Authorization handling is per workflow, but the same rules apply to RetrieveDefinition, Retrieve, and Augment.
  • For basic and digest, the server decodes the incoming bearer value and uses the resulting credentials to authenticate to MarkLogic.
  • For oauth, the bearer token is forwarded on each request rather than cached as a shared server credential.
Alert