Configure MarkLogic MCP Server

You must configure MarkLogic MCP Server to control how it connects to MarkLogic Server, which authentication method it uses, and how it handles sessions and authorization headers.

Configuration of the MarkLogic Retrieval API itself (search behavior, collections, and filters) is separate. See Deploy MarkLogic Retrieval API.

Configuration file structure

The config.yaml file controls MarkLogic MCP Server runtime behavior, including the MarkLogic Server target URL, authentication modes, and workflow module parameters.

Key workflow sections in config.yaml are configured like this:

workflows:
  getRetrieveDefinition:
    context:
      - module: retrieve-definition
        marklogic_url: http://host.docker.internal:8003
        auth_method: digest
  getRetrieve:
    context:
      - module: retrieve
        marklogic_url: http://host.docker.internal:8003
        auth_method: digest
  getAugment:
    context:
      - module: augment
        marklogic_url: http://host.docker.internal:8003
        auth_method: digest

For all supported config.yaml properties, see config.yaml Reference.

MCP sessions and authorization headers

For the complete authorization header contract (expected header format for each authentication mode and failure behavior), see Authorization Header Behavior.

How MCP tools receive authorization through bearer tokens

By default, MCP tools running in MarkLogic MCP Server are stateless: each tool invocation is independent.

Your MCP client must send an Authorization header to MarkLogic MCP Server. MarkLogic MCP Server propagates it to the MarkLogic Server backend.

Basic and digest authentication

1. When using basic or digest authentication with MarkLogic Server, see Basic or digest mode.

2. Configure config.yaml. Ensure that marklogic_url points to your MarkLogic REST app server (reachable from inside the container) and that auth_method is set to digest or basic under each workflow context section:

   marklogic_url: http://host.docker.internal:8003
   auth_method: digest

The MarkLogic MCP Server container receives the bearer token from your MCP client, decodes it, and uses the credentials to authenticate with MarkLogic Server using the method specified by auth_method in config.yaml.

OAuth authentication

1. When using OAuth (such as IdP) authentication for MCP clients, see OAuth/IdP mode.

2. Configure mcp_auth and workflow auth_method in config.yaml:

   Copy

   mra-agent:
     mcp_auth:
       enabled: true
       protected_resource_metadata_url: http://localhost:8088/.well-known/oauth-protected-resource
       authorization_server: https://idp.example.com/realms/MRA
       jwks_url: https://idp.example.com/realms/MRA/protocol/openid-connect/certs
     workflows:
       getRetrieve:
         context:
           - module: retrieve
             marklogic_url: http://host.docker.internal:8003
             auth_method: oauth
   

When you first use an MCP tool, if there is no header, then MarkLogic MCP Server returns the redirection URL. Then, conforming MCP clients follow that URL for authentication:

• Your browser opens to the IdP login page.
• After successful authentication, IdP returns a token.
• The MCP client caches the token and uses it for subsequent requests to MarkLogic MCP Server.

Runtime environment overrides (.env)

While connection settings and workflow rules live in config.yaml, the .env file is used for optional runtime environment overrides:

• MCP_FORCE_HTTPS_METADATA: Force HTTPS for OAuth metadata URLs (set false for local http://localhost testing). For all supported environment variables, see MCP server environment variables.