MCP Client Quickstart | DSX Exchange

Use this guide to open a Model Context Protocol (MCP) session, discover tools, and call one tool through DSX Agent Gateway. The gateway uses the Streamable HTTP transport at /mcp.

For application code, use an MCP client library that supports Streamable HTTP. Use MCP Inspector for interactive requests, or use the manual protocol workflow to inspect HTTP headers, session IDs, and response bodies.

Prerequisites

Obtain the following values from the gateway operator:

The complete HTTPS gateway endpoint URL, including /mcp.
A bearer token from a JSON Web Token (JWT) provider configured for the gateway.
Access to at least one MCP target.

Try It Out

Start with MCP Inspector for an interactive workflow. Use manual protocol verification when you need to inspect the transport exchange.

MCP Inspector

Manual Protocol Verification

Start MCP Inspector

Install Node.js 22.19.0 or later. Start the MCP Inspector web interface:

npx @modelcontextprotocol/inspector

Keep the Inspector bound to a loopback address. Its local proxy can start processes and connect to configured MCP servers, so do not expose it to an untrusted network.

Connect to the Gateway

The command prints a loopback URL for the Inspector. Open that URL in a browser, then configure the connection:

Select the Streamable HTTP transport.
Enter the complete gateway endpoint, including /mcp.
Add an Authorization request header with the value Bearer <access-token>.
Connect to the gateway.

List and Call a Tool

Open the Inspector’s Tools view after the connection succeeds. Select a target-qualified tool, enter its required arguments, and run it. The tool name has the form <target>_<name> when the gateway aggregates multiple targets.

Handle Errors and Retries

Handle HTTP and JSON-RPC errors separately.

Signal	Action
HTTP `401` or `403`	Obtain a valid token or request target access. Do not retry with unchanged credentials.
HTTP `429`	Wait before retrying. Use bounded exponential backoff and limit the retry count.
HTTP `5xx` or a network failure	Retry catalog requests with bounded backoff. Retry a tool call only when its contract permits replay.
Unknown or rejected session	Run `initialize` again and use the new session ID.
JSON-RPC `error`	Correct the method, target name, or parameters before retrying.
`result.isError: true`	Handle the tool-defined failure. Do not assume that replay is safe.

Tool calls can change external state. Do not automatically retry an interrupted tools/call unless the tool is idempotent or supports an idempotency key.

Verify the Connection

The connection is working when all of the following conditions are true.

The client connects through Streamable HTTP with the configured bearer token.
The tool catalog does not contain unauthorized target names.
A call reaches the selected target-qualified tool and returns a result or a tool-defined error.

Use the MCP server publishing guide when a required target is absent from the catalog. Use the operations guide to investigate gateway or dependency failures.