Connect an MCP client

The MCP server supports several clients out of the box. After you add the server, the client opens your browser for a one-time authorization step. See Authorization for details.

Prerequisites

Before you connect a client, make sure that:

  • The Neptune DXP - Open Edition instance is running version 24.15 or later.

  • You have valid Neptune DXP - Open Edition user credentials.

  • You can reach the server from the machine running the client.

  • The server is configured with HTTPS in production. Plain HTTP is only supported for local development.

  • If the server is hosted behind a reverse proxy, the administrator has set the mcpPublicUrl configuration key to the public URL. See Reverse proxy deployments.

Procedure

Claude Code

Claude Code is the Anthropic command-line client for Claude. To connect Claude Code to the MCP server, add a new server entry at user scope so that it is available from any working directory:

claude mcp add --transport http --scope user planet9 https://your-server:port/mcp

Claude Code handles the authorization flow on the first tool call. Your browser opens for sign-in and consent. If you need to start or repeat the authorization manually, for example, after revoking access, run the /mcp slash command inside Claude Code and choose the server.

To verify the connection, run:

claude mcp list

To remove the server, run:

claude mcp remove planet9

Choosing a scope

Claude Code stores MCP server configurations under one of three scopes. The claude mcp list command only shows servers whose scope applies to the current working directory. A server added under local scope therefore appears to disappear when you run the command from a different folder.

Scope Stored where Visible from

user (recommended for single-developer use)

User-level section of ~/.claude.json

Every directory

project

.mcp.json at the project root (commit it to share with teammates)

Anyone who checks out the repository

local (default)

Per-project section of ~/.claude.json

Only the directory it was added from

If you added the server at the default local scope and now want it available everywhere, migrate it to user scope as follows:

# from the directory where it was originally added
claude mcp remove planet9 --scope local

# then re-add at user scope from anywhere
claude mcp add --transport http --scope user planet9 https://your-server:port/mcp

Optional flags

  • --header "Authorization: Bearer <token>" — pre-supply a static token instead of going through the OAuth flow. Most users do not need this option.

Claude Code plugin for Neptune DXP
The Claude Code plugin for Neptune DXP is in active development and still evolving. Tools and behavior may change between releases. Feedback is welcome.
Neptune recommends running the Claude Code plugin against a development or local Neptune DXP instance.

The Claude Code plugin for Neptune DXP connects Claude Code to a Neptune DXP – Open Edition instance 24.15.0 or higher. It registers a Model Context Protocol (MCP) server, exposing tools to read and write Neptune DXP artifacts (apps, server scripts, APIs, tables, and more), and ships a set of skills that teach Claude when and how to use those tools.

Skills

Beyond the MCP tools, the Claude Code plugin also includes a growing set of skills.

These are task-focused guides that Claude only uses when they are relevant. Each skill explains which tools to use and which Neptune DXP conventions to follow for that type of work.

The goal is to equip Claude with the information needed to function as a platform-aware AI assistant, rather than relying solely on general development patterns to infer platform-specific behavior.

Browse the full skill sources in the repository: Claude Code plugin for Neptune DXP

Claude Desktop

Claude Desktop connects to remote MCP servers through its Custom Connectors feature. The local claude_desktop_config.json file is for local stdio servers only and cannot be used to add the MCP server.

To add the MCP server in Claude Desktop:

  1. Open Claude Desktop and go to Settings → Customize → Connectors.

  2. Select Add custom connector.

  3. Enter a name, for example, Neptune, and the server URL: https://your-server:port/mcp.

  4. Click through the OAuth prompt when Claude Desktop opens your browser for sign-in and consent.

Anthropic’s infrastructure connects to your server on your behalf. Your Neptune DXP - Open Edition instance must be publicly reachable from the internet. Claude Desktop cannot reach a server that is only available on your laptop, your VPN, or an internal network unless you expose it, for example, through a tunnel, a VPN gateway, or an allowlisted ingress. If your server is not publicly reachable, use Claude Code instead. Claude Code runs on your machine and can connect to local or VPN-only URLs directly.
Cursor

To add the MCP server in Cursor:

  1. Open Settings → MCP.

  2. Add a new server with the following values:

    Name

    planet9

    Type

    streamable-http

    URL

    https://your-server:port/mcp

Cursor handles the OAuth flow transparently. Your browser opens for sign-in and consent on the first connection.

Windsurf

To add the MCP server in Windsurf:

  1. Open Settings → MCP, or open the MCP panel from the command palette.

  2. Add a new server with the following values:

    Type

    streamable-http

    URL

    https://your-server:port/mcp

Windsurf handles the OAuth flow transparently, like Cursor.

Other MCP clients

Any MCP client that supports the Streamable HTTP transport can connect to the MCP server. The server follows the standard MCP authorization flow:

  1. The initial request to /mcp returns 401 with a WWW-Authenticate header that points the client to the resource metadata.

  2. The resource metadata at /.well-known/oauth-protected-resource/mcp advertises the authorization server.

  3. The authorization server metadata at /.well-known/oauth-authorization-server/mcp/oauth advertises the concrete endpoint URLs.

  4. The client registers itself dynamically at the registration_endpoint from the metadata.

  5. The user authorizes the client at the authorization_endpoint. The browser opens for sign-in and consent.

  6. The client exchanges the authorization code at the token_endpoint for an access token.

Clients must always use the URLs advertised in the metadata documents instead of hard-coding /authorize, /token, and similar paths, because the authorization-server endpoints are mounted at the root of the server.

Some clients, for example, Zed and Continue, currently support only stdio MCP servers. They cannot connect to the MCP server directly. For those clients, you need a bridge process that terminates the OAuth flow locally and re-exposes the tools over stdio.

Related topics