Troubleshooting MCP Server

Common Issues

MCP Server returns HTTP 404 when connecting

Issue

An MCP client fails to connect to the Autonomous AI Database MCP Server and returns the following error: HTTP 404 Not Found

Possible Cause

Possible causes include:

The client configuration uses the authentication endpoint instead of the MCP endpoint.
The MCP Server is not enabled for the database.
The endpoint URL contains an incorrect database OCID or region identifier.
The client attempts to access an MCP path that does not exist.

Resolution

Verify that the MCP Server is enabled for the database.

Confirm that the MCP client configuration uses the correct endpoint format:

https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>

Ensure that the authentication request uses the token endpoint:
```
/adb/auth/v1/databases/<database-ocid>/token
```
Verify that the region identifier and database OCID match the target Autonomous AI Database.

Additional Information

The MCP endpoint and the authentication endpoint use different paths.

The authentication endpoint issues OAuth tokens, while the MCP endpoint processes tool and agent requests.

Verify that the MCP Server is enabled for the database. See Enable MCP Server on how to enable the MCP Server.

MCP Client Authentication Fails When Requesting Token

Issue

An MCP client fails to obtain a bearer token and returns an authentication error when calling the token endpoint.

Possible Cause

Possible causes include:

The database username or password is incorrect.
The token request uses an incorrect endpoint.
The database user account is locked or expired.
Network access restrictions block the request.

Resolution

Confirm that the token request uses the authentication endpoint.

https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token

Verify the database username and password used in the request.
Confirm that the database user account is active.

Retry the request with a valid token.

Example request:

curl --location "https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token" \
--header "Content-Type: application/json" \
--data '{"grant_type":"password","username":"ADMIN","password":"<password>"}'

Additional Information

The authentication service issues a bearer token that MCP clients include in the Authorization header when calling MCP tools.

Invalid Client Error Appears In the Browser During Authentication

Issue

The authentication page displays the following message when signing in to the MCP server:

Invalid Client

Possible Cause

Possible causes include:

Cached authentication data stored by the MCP client.
A stale authentication session created during a previous login attempt.

Resolution

Navigate to your home directory.
Locate the .mcp_auth directory.

Example locations:

Linux / macOS
```
~/.mcp_auth
```
Windows
```
C:\Users\<username>\.mcp_auth
```
Delete the .mcp_auth directory to clear the cached authentication session.
Restart the MCP client and authenticate again.

MCP Tools Do Not Appear in the MCP Client

Issue

An MCP client connects successfully to the MCP Server but does not display any tools.

Possible Cause

Possible causes include:

No custom tools have been created.
The client user does not have sufficient privileges to access the tools.
The MCP tool creation failed during creation.
The tool status is disabled.

Resolution

Confirm that tools exist in the database.
Verify that the tools are created successfully. See Create Select AI Agent Tools for more details.
Ensure that the database user connecting through MCP has the privileges required to access the tool.
Restart or reconnect the MCP client so it refreshes the tool list.

Tool Call Fails After Approval

Issue

The tool call fails even after the user approves it.

Possible Cause

The bearer token expired or the schema user does not match the tool owner.

Resolution

Generate a new bearer token.
Verify that the schema user created the tools.

Confirm that the tools exist.

SELECT tool_name FROM user_cloud_ai_tools;

Restart the client and retry.

Streamable HTTP Error – 401

Issue

The client shows the message Streamable HTTP error: Server returned 401 after successful authentication.

Possible Cause

The bearer token is expired or no longer valid. Bearer tokens are valid for approximately one hour.

Resolution

Generate a new bearer token using the OAuth endpoint.
Replace the Authorization header value with the new token.
```
"Authorization": "Bearer <new-access-token>"
```
Save the MCP configuration file.
Restart the client.
Reconnect to the MCP Server.
Reissue the prompt.

Unexpected Empty Results

Issue

The tool call succeeds but returns no rows.

Possible Cause

The table contains no matching rows or the filter conditions are too restrictive.

Resolution

Verify the table contains data.
Check the filter conditions used in the query.
Confirm the correct schema and table are referenced.

Test the query in SQL Worksheet.

SELECT COUNT(*) FROM <table_name>;

MCP Server Connection Fails When Database Uses A Private Endpoint

Issue

An MCP client cannot connect to the MCP Server for a database configured with a Private Endpoint.

Possible Cause

Possible causes include:

The client attempts to connect from outside the configured VCN.
The MCP endpoint URL uses the public hostname instead of the private endpoint hostname.
Network security rules block the request.

Resolution

Confirm that the database uses a Private Endpoint.
Retrieve the private endpoint hostname prefix from the Autonomous AI Database console.

Update the MCP endpoint URL. See Private Endpoint Access for more details.

Example format:

https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>

Ensure the MCP client runs within the VCN or connected network.

Fetch Failed Error

Issue

The client shows a fetch failed error when connecting to the MCP Server.

Possible Cause

The MCP URL is incorrect, HTTP is used instead of HTTPS, the region identifier is wrong.

Resolution

Verify that the endpoint uses https, not http.
Confirm the domain uses oraclecloudapps.com, not oraclecloud.com.
Verify the region identifier and database OCID.
Retry the connection after updating the configuration.

Connection Drops During Session

Issue

The client stops working during an active session.

Possible Cause

The bearer token expired during the session.

Resolution

Generate a new bearer token.
Update the configuration file.
Restart the client.
Reconnect to the MCP Server.

Claude Troubleshooting

Claude Does Not Prompt for Database Credentials

Issue

Claude Desktop does not display a login prompt for database credentials after restart.

Possible Cause

Cached authentication data is interfering.

Resolution

Open Claude Desktop.
Click Menu, select Help, and then click Troubleshooting.
Choose Clear Cache and Restart.
Restart Claude and retry the connection.
If the issue persists, delete the .mcp_auth folder from your user directory.
Clear browser cookies for dataaccess.adb.<region>.oraclecloudapps.com.
Restart Claude again and retry.

MCP Server Does Not Show as Running

Issue

Claude Desktop does not show the MCP Server in a Running state.

Possible Cause

The MCP feature is disabled, the endpoint is incorrect, or the client configuration is incomplete.

Resolution

Verify that the free-form tag value is set correctly.
```
{"name":"mcp_server","enable":true}
```

Confirm the endpoint uses:

https://dataaccess.adb.<region>.oraclecloudapps.com

.

Restart Claude after validating the configuration.

Claude Desktop Shows the MCP Server As Disabled

Issue

After adding an MCP server configuration in Claude Desktop, the MCP server appears disabled and tools are not available.

Possible Cause

Possible causes include:

No Select AI Agent tools are created for the database user.
Claude Desktop started before the MCP tools were created.
The MCP client cached an earlier tool configuration.

Resolution

Confirm that Select AI Agent tools exist for the database user. See USER_AI_AGENT_TOOLS View to get a list of the tools for the database user.
Example:
```
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/
            
```
Restart Claude Desktop after adding or modifying MCP tools.
Reconnect the MCP server in Claude Desktop.

Tools Do Not Appear After Login in Claude

Issue

Claude connects successfully, but the expected tools do not appear.

Possible Cause

You logged in as a different schema user, the tools were created under another schema, or Claude needs to be restarted after tool creation.

Resolution

Confirm you logged in as the same schema user who created the tools.
Verify that the tools exist in the database.
```
SELECT tool_name FROM user_cloud_ai_tools;
```
Restart Claude Desktop after verification.

Claude Connects but Behaves Unexpectedly

Issue

Claude loads and connects, but the responses do not match the expected behavior.

Possible Cause

The current chat session contains stale context, the session needs to be refreshed, or tool permissions are not configured as expected.

Resolution

Start a new chat session.
Restart Claude Desktop.
Reconnect to the MCP Server.
Verify tool permissions under Connectors.

Cline Troubleshooting

No Chat Box Visible in Cline

Issue

The Cline chat input box is not visible after viewing MCP server configuration and tools.

Possible Cause

The user is still in the MCP configuration panel.

Resolution

Click Done in the MCP configuration panel.
Return to the Cline chat interface.
Enter the prompt again in the chat box.

Metadata Request Fails Unexpectedly

Issue

The metadata request fails or returns an unexpected result when the user asks for table metadata.

Possible Cause

The session connection became stale, the prompt history affected tool selection, or the same table exists in multiple schemas.

Resolution

Reconnect to the MCP Server.
Clear the prompt history or start a new chat session.
Reissue the metadata prompt.
If the same table exists in multiple schemas, qualify the table with the schema name.
```
Show the metadata details of SALES_USER.CUSTOMERS
```

Verify duplicate table names in the database.

SELECT owner, table_name
                FROM all_tables
                WHERE table_name = 'CUSTOMERS';