Troubleshoot MarkLogic MCP Server

Follow this troubleshooting guidance to quickly isolate whether a problem is in your MCP client, MarkLogic MCP Server, or MarkLogic Retrieval API deployment.

No tools visible in the MCP client

Symptoms:

• MCP server does not appear in the client
• server appears, but RetrieveDefinition, Retrieve, and Augment are missing

Checks:

1. Confirm that the MCP URL shape is correct: http://<host>:8088/api/v1/agent/mra-agent/session/<session-id>/mcp
2. Confirm that MarkLogic MCP Server is running by using docker compose ps in the directory containing your docker-compose.yaml file.
3. If you have edited your MCP client configuration, reload or restart the MCP client.
4. In VS Code Copilot, type # in chat input to list tools.
5. Verify server registration with your client’s MCP server listing UI/command.

Authentication failures

Symptoms:

• 401 responses
• OAuth redirects not completing
• "invalid token" / "authorization required"

For the expected header format per auth mode, see Authorization Header Behavior.

Basic or digest mode

1. Confirm auth_method is set to basic or digest under workflow context blocks in config.yaml.
2. Confirm your MCP client sends:
   • Authorization: Bearer <base64(username:password)>
3. Re-generate the token if credentials changed:

echo -n "username:password" | base64

OAuth/IdP mode

1. Confirm auth_method is set to oauth under workflow context blocks and mcp_auth.enabled is true in config.yaml.
2. Remove static auth headers from client config.
3. Confirm that authorization_server in config.yaml is reachable from the MCP client environment.
4. In VS Code dynamic registration, use MCP client ID configured in your IdP provider. See your IdP admin for more information.
5. If VS Code appears stuck on old credentials, clear old dynamic providers:
   • Open Command Palette and run Authentication: Remove Dynamic Authentication Providers.
   • Remove entries for your MCP host, then retry.
6. Retry a tool call to trigger login flow.

OAuth/IdP symptom

When connecting the client, the OAuth login popup fails with an error related to redirect_uri. The authorization URL typically includes a callback such as https://example.com/sn/oauthcallback or https://vscode.dev/redirect.

Cause:

Many IdPs only permit redirect URIs explicitly configured for the OAuth client. If the client callback URL is missing from the client configuration, the IdP rejects the authorization request.

Resolution:

Add the client callback URL to the list of valid redirectUris in your IdP.

Connection failures

Symptoms:

• "connection refused"
• timeouts
• client can reach the MarkLogic MCP Server, but the server cannot reach MarkLogic

Checks:

1. Confirm the MarkLogic MCP Server endpoint is reachable:

curl -i http://localhost:8088/

2. Confirm MarkLogic REST app server endpoint is reachable directly:

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

3. If the MarkLogic MCP Server runs in Docker and MarkLogic Server runs on host, check marklogic_url in config.yaml:
   • marklogic_url: http://host.docker.internal:<port>
4. Ensure host/port values match what your MarkLogic REST app server actually uses.

Is MRA deployed and responding?

Before debugging MCP behavior, verify MRA itself:

curl --anyauth -u <user>:<password> http://<host>:<port>/v1/retrieve/definition

If this fails, fix deployment/config first:

• Deploy MarkLogic Retrieval API

Check MarkLogic Server logs

If endpoint checks fail or return unexpected server errors, inspect MarkLogic Server logs directly.

If MarkLogic Server is running in Docker

Run the following from the directory containing the docker-compose.yaml that defines your MarkLogic Server container, substituting the service name used in that file for marklogic:

docker compose logs marklogic

Use -f to follow logs while reproducing a failing request:

docker compose logs -f marklogic

If MarkLogic Server is running outside Docker

Check the MarkLogic Server Logs directory (default: /var/opt/MarkLogic/Logs/) and inspect:

• ErrorLog.txt (server/runtime errors)
• Error/access logs for your REST app server (for request-level failures)

What to look for

• authentication/authorization failures
• rewriter or endpoint module load errors
• JavaScript/XQuery runtime exceptions from endpoint code
• host/port/TLS connection failures when calling dependent services

Fast isolation decision tree

1. If the client cannot discover MCP tools, troubleshoot client registration / MCP URL / server startup first.
2. If tools are visible but calls fail with auth errors, troubleshoot auth mode and headers/tokens.
3. If auth looks correct but tool calls still fail, verify MRA endpoint health with direct curl.