config.yaml reference

Save PDF

Last Updated: September 9, 2026
4 minute read

Documentation

The config.yaml file is the central configuration file for the MarkLogic MCP Server. It defines agent details, OAuth authentication rules for MCP clients (mcp_auth), and workflow module definitions for connecting to the MarkLogic Retrieval API (workflows).

Configuration Structure Overview

A complete config.yaml file contains the following top-level structure:

mra-agent:
  title: MarkLogic Retrieval API Agent
  description: MarkLogic Retrieval API agent for retrieving data from MarkLogic Server for various use cases.
  instructions: You are a helpful research assistant, adept at searching databases for relevant documents and extracting information to answer user queries.
  drivers: []
  mcp_auth:
    enabled: false
    protected_resource_metadata_url: null
    authorization_server: null
    jwks_url: null
    scopes_supported:
      - openid
      - profile
      - email
  rules:
    rules:
      - prompt: Be polite and concise.
  workflows:
    getRetrieveDefinition: ...
    getRetrieve: ...
    getAugment: ...

Top-Level Agent Properties

title — String (required): Display title for the agent.
description — String (required): Description of the agent purpose and capabilities.
instructions — String (required): System instructions provided to the agent model.
drivers — Array (required): List of driver extensions. For MarkLogic Retrieval API, keep this as an empty array [] because retrieval is handled by workflow modules.

MCP Auth Configuration (`mcp_auth`)

The mcp_auth block controls OAuth authentication required from MCP clients connecting to the MCP Server.

enabled — Boolean (required): Set to true to require OAuth authentication from MCP clients. Set to false for standard Basic/Digest credential passthrough.
protected_resource_metadata_url — String (optional): URL advertising protected resource metadata to MCP clients (for example, http://localhost:8088/.well-known/oauth-protected-resource).
authorization_server — String (optional): OAuth Authorization Server issuer URL (for example, https://idp.example.com/realms/MRA).
jwks_url — String (optional): JWKS endpoint URL used to validate incoming JWT bearer tokens from clients.
scopes_supported — Array of Strings (optional): Supported OAuth scopes (for example, ["openid", "profile", "email"]).

Workflow Definitions (`workflows`)

The workflows section defines the three tools exposed to MCP clients: getRetrieveDefinition (RetrieveDefinition), getRetrieve (Retrieve), and getAugment (Augment).

Each workflow defines a context block with connection properties for communicating with the upstream MarkLogic REST App Server:

context:
  - module: retrieve
    id: retrieve
    title: Retrieve
    prune_context: false
    marklogic_url: http://host.docker.internal:8003
    auth_method: digest
    transport_verify: false
    allow_private_url: true

Context Module Properties

marklogic_url — String (required): Base URL for the target MarkLogic REST app server (for example, http://host.docker.internal:8003 or http://localhost:8003). Must be reachable from inside the MCP server container.
auth_method — String (optional): Authentication scheme used when calling MarkLogic. Default: oauth. Valid values: digest, basic, oauth, and jwt. Use digest or basic to forward credentials decoded from the incoming Authorization header; use oauth or jwt to forward the caller's bearer token to MarkLogic Server.
jwt_token — String (optional): Static JWT used only by non-MCP consumers that create a MarkLogic connection directly. MarkLogic MCP Server ignores this property.

When auth_method is jwt, every tool call requires an Authorization bearer token on the incoming MCP request:

If a bearer token is present, that token is forwarded to MarkLogic Server. jwt_token is not consulted.
If no bearer token is present, the request is rejected with an authentication error. jwt_token is not consulted.

Because the request is rejected before a connection is created, there is no path through the MCP server in which jwt_token is used. It exists for other consumers of the underlying MarkLogic context module that construct a connection directly rather than through an MCP request.

Note: For MCP clients, auth_method: jwt and auth_method: oauth behave the same way: both require an incoming bearer token and forward it unchanged to MarkLogic Server. Prefer oauth, which is the documented mode for identity-provider integration.

transport_verify — Boolean (optional): Controls whether TLS certificates are verified when connecting to MarkLogic REST app server over HTTPS. Default: true. The example configuration sets it to false for local development against a self-signed or plain HTTP endpoint; leave it at the default of true in production.
allow_private_url — Boolean (optional): Controls whether connections to private IP addresses or loopback hostnames (for example, host.docker.internal, 127.0.0.1) are permitted. Default: false. The example configuration sets it to true because the MCP server container reaches MarkLogic Server over host.docker.internal. Leave it at the default of false unless your deployment requires private-network access.
prune_context — Boolean (optional): Controls context pruning in workflow execution. Default: false.

Example `config.yaml`

Below is a complete, working example of config.yaml using Digest authentication:

mra-agent:
  title: MarkLogic Retrieval API Agent
  description: MarkLogic Retrieval API agent for retrieving data from MarkLogic Server for various use cases.
  instructions: You are a helpful research assistant, adept at searching databases for relevant documents and extracting information to answer user queries.
  drivers: []
  mcp_auth:
    enabled: false
    protected_resource_metadata_url: null
    authorization_server: null
    jwks_url: null
    scopes_supported:
      - openid
      - profile
      - email
  rules:
    rules:
      - prompt: Be polite and concise.
  workflows:
    getRetrieveDefinition:
      name: RetrieveDefinition
      description: Retrieve a definition from MarkLogic.
      parameters: {}
      required: []
      preprocess: []
      context:
        - module: retrieve-definition
          id: retrieve-definition
          title: Retrieve Definition
          prune_context: false
          marklogic_url: http://host.docker.internal:8003
          auth_method: digest
          transport_verify: false
          allow_private_url: true
      generation:
        - module: passthrough
      postprocess: []
    getRetrieve:
      name: Retrieve
      description: Retrieve documents from MarkLogic REST app server for a given query.
      parameters:
        retrieveQuery:
          type: string
          description: >
            JSON string to POST as the body to the MarkLogic REST app server /v1/retrieve endpoint.
      required:
        - retrieveQuery
      preprocess: []
      context:
        - module: retrieve
          id: retrieve
          title: Retrieve
          prune_context: false
          marklogic_url: http://host.docker.internal:8003
          auth_method: digest
          transport_verify: false
          allow_private_url: true
      generation:
        - module: passthrough
      postprocess: []
    getAugment:
      name: Augment
      description: Augment (fetch full document content) from MarkLogic REST app server by document URIs.
      parameters:
        augmentRequest:
          type: string
          description: >
            JSON string specifying the documents to fetch from the MarkLogic REST app server /v1/retrieve/augment endpoint.
      required:
        - augmentRequest
      preprocess: []
      context:
        - module: augment
          id: augment
          title: Augment
          prune_context: false
          marklogic_url: http://host.docker.internal:8003
          auth_method: digest
          transport_verify: false
          allow_private_url: true
      generation:
        - module: passthrough
      postprocess: []

MCP Server Environment Variables — Reference for optional runtime environment overrides.
Authorization Header Behavior — Details on how authorization headers are processed for each auth_method.
Configure MarkLogic MCP Server — Step-by-step guide to configuring the MCP server.

MarkLogic MCP Server