Deploy MarkLogic Retrieval API

Use the mra-deployer as part of the marklogic-mcp-<version>.zip deployment package to install MarkLogic Retrieval API (MRA) into an existing MarkLogic REST app server. Download the package from the marklogic-mcp-deployer GitHub releases page.

Prerequisites

• MarkLogic Server 11+
• A running MarkLogic REST app server attached to a content database and its schemas database
• Vector embeddings in configured TDE vector columns if you plan to use vector search
• Java 17+
• A terminal in the mra-deployer/ directory of the extracted marklogic-mcp-<version>.zip deployment package

Configure the MRA deployer

Open mra-deployer/gradle.properties, and update these values to reflect your REST app server settings:

mlAppName=mra-deployer-test
mlHost=localhost
mlRestPort=8003
mlUsername=admin
mlPassword=admin
mlAuthentication=digest
mlModulesDatabaseName=mra-deployer-test-modules
mlSchemasDatabaseName=mra-deployer-test-schemas

Install MRA

From the mra-deployer/ directory, run this command:

./gradlew installMra

This command does these tasks:

• Loads the MRA modules.
• Deploys the MRA app server configuration.
• Deploys roles, users, and other configuration objects.
• Loads the default retrieveConfig.json into the schemas database.
• Preserves the original REST app server rewriter so that it can be restored later.

Verify deployment

1. Check the definition endpoint with this command:

   Copy

   curl --digest -u admin:admin http://localhost:8003/v1/retrieve/definition
   

   This command returns a JSON response describing the deployment, labels, filters, schemas, and search metadata.

2. Test retrieval based on your dataset with this command:

   Copy

   curl -X POST http://localhost:8003/v1/retrieve \
     --digest -u admin:admin \
     -H "Content-Type: application/json" \
     -d '{"text":"diabetes OR insulin","topk":5}'
   

Grant access to users

Assign the mra-reader role to MarkLogic Server users who need to call MRA.

Redeploy after changes

After initial installation, if you download a new version of the deployment package, then follow these steps:

1. Change these files to match your new configuration:

   • mra-deployer/src/main/ml-schemas/marklogic-retrieval-api/retrieveConfig.json — your own copy of the retrieve configuration. See Maintaining Your Own retrieveConfig.json.
   • deployer config in gradle.properties

2. Run ./gradlew installMra again.

To deploy a change to retrieveConfig.json on its own, without reinstalling MRA, run ./gradlew mlLoadSchemas.

Disable MRA

To disable MRA and restore the original rewriter, use ./gradlew disableMra.

Remove MRA

To remove MRA modules, config, roles, users, and amps, use ./gradlew uninstallMra.

Troubleshooting

• Confirm that mlHost, mlRestPort, mlUsername, and mlPassword are correct.
• Confirm that the MarkLogic REST app server is running.
• Inspect the installMra output for role, module, or schema errors.

Once MRA is deployed, configure MarkLogic MCP Server.