Configure an MCP client

This section explains how to configure your MCP client (VS Code Copilot, Claude Desktop, or similar) to connect to MarkLogic MCP Server. Once connected, your MCP client can call the MarkLogic Retrieval API (MRA) tools to search and retrieve content from your MarkLogic Server databases.

Before using this section, complete either Quick start or both Deploy MarkLogic Retrieval API and Configure MarkLogic MCP Server.

Identify your MCP endpoint

Use the MCP endpoint exposed by MarkLogic MCP Server:

http://<mcp-server-host>:8088/api/v1/agent/mra-agent/session/<session-id>/mcp

Example:

http://localhost:8088/api/v1/agent/mra-agent/session/session-1/mcp

Session ID convention

• The <session-id> can be any stable identifier that you choose.
• Reuse the same session ID to keep requests in the same MCP session context.
• Use different session IDs to isolate independent workflows.
• ephemeral is also a valid session ID value. It is just an opaque string, not a special mode.

Add MarkLogic MCP Server to your MCP client configuration

Most MCP clients need an MCP server entry with these values:

• An MCP server name. Example: MarkLogicMCP
• A type. Example: HTTP
• An MCP server endpoint URL. Example: http://localhost:8088/api/v1/agent/mra-agent/session/<session-id>/mcp

Full example:

{
  "servers": {
    "MarkLogicMCP": {
      "type": "http",
      "url": "http://localhost:8088/api/v1/agent/mra-agent/session/<session-id>/mcp"
    }
  }
}

Configure authentication behavior

Authentication occurs according to how the target MarkLogic REST app server and MarkLogic MCP Server are configured with the auth_method property in config.yaml.

Basic or digest mode

For basic or digest mode, you must add an Authorization header containing the base64-encoded username:password as a bearer token.

1. Generate a token with this command:

   Copy

   echo -n "username:password" | base64
   

2. Provide the token as in this MCP client configuration example:

   Copy

   {
     "servers": {
       "MarkLogicMCP": {
         "type": "http",
         "url": "http://localhost:8088/api/v1/agent/mra-agent/session/<session-id>/mcp",
         "headers": {
           "Authorization": "Bearer <base64-username:password>"
         }
       }
     }
   }
   

OAuth/IdP mode

For OAuth/IdP mode, remove the Authorization header from the MCP client configuration and use the plain MCP URL to let the OAuth redirect and login flow handle tokens as in this example:

{
  "servers": {
    "MarkLogicMCP": {
      "type": "http",
      "url": "http://localhost:8088/api/v1/agent/mra-agent/session/<session-id>/mcp"
    }
  }
}

Verify that the tools are visible

1. Save the MCP client configuration.
2. Reload or restart the MCP client.
3. Verify that these tools have been discovered:
   • RetrieveDefinition
   • Retrieve
   • Augment

In VS Code

• To list tools from active MCP servers: Type # in the chat input area to trigger the tool list. The list displays all tools from all registered MCP servers.
• To open the tools picker: Click the Tools icon in the chat input area to see an interactive tool picker where you can view tool descriptions and parameters.

If the tools do not appear, verify the following conditions:

1. The client configuration file contains a valid MCP server entry with a correct URL.
2. MarkLogic MCP Server is running and accessible at the configured URL.
3. Authentication credentials are correct.
4. The user has the mra-reader role in MarkLogic Server. For further help, see Troubleshoot MarkLogic MCP Server.

Smoke test with a simple request

1. Use your client to call RetrieveDefinition. A JSON response returns with information about the target database including labels (MarkLogic Server collections), filters, schemas, and search metadata.

2. Run a small Retrieve query to confirm that the search returns document URIs.

In VS Code

You can try the following prompts in the AI chat of VS Code:

Use the MarkLogicMCP_RetrieveDefinition tool and show me the result.

Use the MarkLogicMCP_Retrieve tool to search for diabetes treatment documents.
Return the URIs and cite them.

Use the MarkLogicMCP_Augment tool for one result and show the document content.

A successful connection exhibits the following characteristics:

• The client recognizes the MarkLogic MCP Server configuration and loads it without errors.
• The three tools (RetrieveDefinition, Retrieve, Augment) are visible in the tools list.
• Tool invocations complete without authentication errors (no 401 Unauthorized responses).
• Tool responses contain valid JSON data: configuration data for RetrieveDefinition, search results for Retrieve, or document content for Augment. If Retrieve or Augment return empty results, then verify that your MarkLogic Server database contains data and that the search query is valid.

Implementation notes:

• Tool name prefixing: The exact tool name displayed in the MCP client may be prefixed with your MCP server name. For example, if you named your MCP server MarkLogicMCP, then the full tool name may appear as MarkLogicMCP_Retrieve rather than just Retrieve.
• Security considerations: Authorization tokens embedded in client configuration files are credential-bearing. For development and testing on localhost-only machines, this approach is acceptable. For production deployments and environments accessible over networks, use OAuth authentication instead of basic or digest authentication.

Troubleshooting

• If no tools appear, then verify the MCP server URL, and verify that MarkLogic MCP Server is running on port 8088.
• If you get auth errors, then verify that the authentication mode and the header behavior match your MarkLogic MCP Server configuration.
• If OAuth does not start, then verify that authorization_server in config.yaml is reachable from the MCP client environment.