Skip to main content

Installation

Configure your IDE to connect to the Candescent MCP Server. No separate server package is required for the hosted beta — add the MCP URL, bearer token, and transactionId to your IDE's mcp.json.

Beta

The MCP Server is in beta for testing only. Endpoint URLs and configuration options may change.

Prerequisites​

Before connecting:

  • API credentials for Stage and Sandbox — Shared Key (client_id) and Secret Key (client_secret). No separate MCP-specific keys are required.
  • An IDE with MCP server support — for example Cursor or another editor that supports remote MCP servers over HTTP
  • A valid OAuth access token (bearer token)

MCP Endpoint URLs​

EnvironmentMCP URL
Stagehttps://api.stage.candescent.com/mcp
Sandboxhttps://api.sandbox.candescent.com/mcp

Obtain a Bearer Token​

Exchange your Shared Key (client_id) and Secret Key (client_secret) for an access token before editing mcp.json. Follow Create OAuth Token (V2) and use the server host that matches your target environment (api.stage.candescent.com or api.sandbox.candescent.com).

Copy the access_token value from the response. Access tokens expire (typically within ~24 hours per the current API contract) — refresh the token and update mcp.json when you receive 401 Unauthorized.

Configure mcp.json​

Add the MCP server in your IDE's MCP settings. In Cursor, use Settings → MCP or edit your user/project mcp.json. Other MCP-capable IDEs use the same JSON shape — check your editor's documentation for where to place the file.

Include the MCP URL, bearer token, and a transactionId header. transactionId must be a UUID that uniquely identifies each logical transaction.

{
  "mcpServers": {
    "candescent-digital-banking": {
      "url": "https://api.stage.candescent.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }
}

Replace YOUR_ACCESS_TOKEN with the access_token from the Create OAuth Token (V2) response.

Verify Connectivity​

After configuration:

  1. Restart your IDE or reload MCP servers from the MCP panel.
  2. Confirm candescent-digital-banking shows as connected.
  3. Proceed to Quick Start to list tools and run a test invocation.

Troubleshooting​

SymptomWhat to check
MCP server shows disconnectedVerify the URL includes /mcp and uses https://
401 UnauthorizedRefresh your bearer token and update Authorization in mcp.json
400 Bad RequestConfirm transactionId is a valid UUID
No tools listedConfirm your app has entitlements for the beta MCP surface; try Stage first
SSL or network errorsEnsure your network allows outbound HTTPS to api.stage.candescent.com or api.sandbox.candescent.com

MCP Inspector​

For connection and tool-call issues, use the official MCP Inspector to test the Candescent MCP server outside your IDE. It provides a browser UI to verify the handshake, list tools, invoke operations, and inspect raw JSON-RPC request and response messages.

  1. Run the Inspector (requires Node.js):
Bash
npx @modelcontextprotocol/inspector
  1. Open the client UI (default http://localhost:6274).
  2. Connect using streamable HTTP with the same MCP URL and headers from your mcp.json (Authorization, transactionId).
  3. Use the Tools tab to test operations such as listing accounts before troubleshooting in Cursor.

This isolates server, token, and parameter problems from IDE-specific MCP client behavior.

Known Errors​

The following messages may appear in Cursor or other MCP-capable IDEs during the beta release. They are known compatibility issues between the Candescent MCP server, OpenAPI-derived tool schemas, and IDE MCP clients — not misconfiguration of your mcp.json.

Method ping is not supported (-32601)​

Cursor may log this error in the MCP output panel:

Method ping is not supported

The Candescent MCP server does not yet implement the ping method some IDE clients send during streamable HTTP setup. You can often ignore this error if tool calls still work.

Cursor may log an error such as:

Invalid parameter names found: tool listAccountsV1: parameter $apply contains invalid characters or is too long

Some tools expose OData query parameters from the OpenAPI spec ($apply, $filter, $skipGroups, $topGroups). Cursor rejects parameter names that start with $. Tool calls that use other parameters — for example hostUserId, viewName, or loginId — may still work. Use MCP Inspector to test OData-style parameters outside Cursor.

Next Steps​