HTTP Authentication

When using HTTP transport mode, the Neo4j MCP server supports two authentication methods to accommodate different deployment scenarios:

Bearer token authentication

Bearer token authentication enables seamless integration with Neo4j Enterprise Edition and Neo4j Aura environments that use Single Sign-On (SSO)/OAuth/OIDC for identity management. This method is ideal for:

  • Enterprise deployments with centralized identity providers (Okta, Azure AD, etc.)

  • Neo4j Aura databases configured with SSO

  • Organizations requiring OAuth 2.0 compliance

  • Multi-factor authentication scenarios

The bearer token is obtained from your identity provider and passed to Neo4j for authentication. The MCP server acts as a pass-through, forwarding the token to Neo4j’s authentication system.

  1. Start your Neo4j MCP server in HTTP mode:

    export NEO4J_URI="bolt://localhost:7687"
export NEO4j_TRANSPORT_MODE="http"
neo4j-mcp

    The server starts on http://127.0.0.1:80 by default.

  2. Create or edit your mcp.json file, for example for Neo4j Enterprise or Aura with SSO/OAuth configured:

    {
  "servers": {
    "neo4j-http-bearer": {
      "type": "http",
      "url": "http://127.0.0.1:80/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
}

    Replace the bearer token with your actual OAuth/SSO token from your identity provider.

Basic authentication

Basic authentication with username and password is suitable for:

  • Neo4j Community Edition

  • Development and testing environments

  • Direct database credentials without SSO

    1. Start your Neo4j MCP server in HTTP mode:

      export NEO4J_URI="bolt://localhost:7687"
export NEO4j_TRANSPORT_MODE="http"
neo4j-mcp

      The server starts on http://127.0.0.1:80 by default.

    2. Create or edit your mcp.json file:

      {
  "servers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:80/mcp",
      "headers": {
        "Authorization": "Basic BASE64_ENCODED_CREDENTIALS"
      }
    }
  }
}

    3. Generate the base64-encoded credentials:

      echo -n "neo4j:password" | base64

Select an authentication method

Use Bearer Token when:

  • You’re using Neo4j Enterprise Edition or Aura with SSO/OIDC/OAuth configured

  • You want to integrate with your organization’s identity provider

  • You need to support OAuth 2.0 flows

Use Basic Auth when:

  • You’re using traditional username/password authentication

  • You’re using Neo4j Community Edition

  • You have direct database credentials

Custom auth header name

By default, the server reads credentials from the Authorization header. You can change the header name the server reads from by setting the environment variable NEO4J_HTTP_AUTH_HEADER_NAME or passing the CLI flag --neo4j-http-auth-header-name when starting neo4j-mcp.

Example with custom header X-Test-Auth:

export NEO4J_TRANSPORT_MODE="http"
export NEO4J_HTTP_AUTH_HEADER_NAME="X-Test-Auth"
neo4j-mcp

Then configure your MCP client to send the custom header, for example in mcp.json:

{
  "servers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:80/mcp",
      "headers": {
        "X-Test-Auth": "Bearer <your-sso-token-here>"
      }
    }
  }
}

Troubleshooting authentication

Bearer Token Issues

401 Unauthorized - Token not accepted

  • Verify your Neo4j instance is Enterprise Edition or Aura with OAuth/SSO configured

  • Community Edition does not support bearer token authentication - use Basic Auth instead

  • Confirm the token hasn’t expired - bearer tokens typically have short lifespans (15-60 minutes)

  • Check with your identity provider to ensure the token is valid

Invalid token format

  • Ensure the header format is exactly: Authorization: Bearer YOUR_TOKEN

  • No extra spaces before or after "Bearer"

  • Token should not be base64-encoded (unlike Basic Auth)

Neo4j rejects valid token

  • Verify your Neo4j instance is configured to accept tokens from your identity provider

  • Check Neo4j server logs for specific authentication errors

  • Confirm the token issuer matches Neo4j’s OAuth configuration

Basic auth issues

401 Unauthorized - Credentials not accepted

  • Verify username and password are correct

  • Check that credentials are properly base64 encoded: echo -n "user:pass" | base64

  • Ensure the authorization header format is: Authorization: Basic BASE64_STRING

Empty credentials error

  • Both username and password must be non-empty

  • The base64 string must decode to username:password format with both parts present

General issues

No authentication header provided

  • HTTP mode requires authentication on every request

  • Ensure your MCP client configuration includes the Authorization header

Connection refused / Cannot reach server

  • Verify the Neo4j MCP server is running in HTTP mode

  • Check the server is listening on the correct host:port

  • Confirm firewall rules allow connections to the MCP server port