BridgeXAPI MCP Discovery Lab

From zero to your first AI-agent-readable BridgeXAPI interaction.

This lab shows how an MCP-compatible client discovers BridgeXAPI capabilities through the official MCP Inspector.

Goal

By the end of this lab, you will understand how an AI agent can:

• connect to the BridgeXAPI MCP server

• discover available messaging tools

• inspect tool schemas

• execute tools manually

• understand the same flow Claude or another MCP-compatible agent would use

Screenshots

All screenshots are stored in:

/screenshots

Step 1 — Verify Node.js

node -v
npm -v

Step 2 — Start the MCP Inspector

Launch the official Model Context Protocol Inspector using npx.

npx @modelcontextprotocol/inspector

The first execution downloads the Inspector package from npm. After the installation completes, the Inspector starts a local proxy server and automatically opens your default browser.

You should see output similar to this:

The terminal displays:

• the local Inspector URL

• the local proxy server

• the temporary session token used by the Inspector

Leave this terminal running while you complete the rest of the lab.

Step 3 — Open the Inspector

Once the Inspector has started, your browser will automatically open the local web interface.

If it does not open automatically, navigate to the URL displayed in the terminal, for example:

http://localhost:6274

The Inspector provides a graphical interface for connecting to any MCP-compatible server.

Before connecting, you'll see the initial landing page:

At this point the Inspector is not connected to BridgeXAPI. It is simply waiting for you to configure an MCP server.

Step 4 — Connect to the BridgeXAPI MCP Server

The Inspector is currently running, but it is not connected to any MCP server.

In this step we'll configure the BridgeXAPI Agent Interface.

4.1 Select the transport

By default, the Inspector expects a local MCP server running over STDIO.

BridgeXAPI exposes its Agent Interface over HTTP, so we need to change the transport.

Select:

Streamable HTTP

4.2 Configure the BridgeXAPI MCP endpoint

Now configure the MCP server you want the Inspector to connect to.

Enter the BridgeXAPI MCP endpoint:

https://agent.bridgexapi.io/mcp

Leave the connection type set to Via Proxy.

At this point, the Inspector knows where the BridgeXAPI MCP server is located, but no connection has been established yet.

4.3 Authentication

The BridgeXAPI MCP server supports an initial MCP session without requiring authentication.

The Authentication section is available for deployments or capabilities that require credentials.

For this guide, no additional authentication is required to establish the initial MCP session.

4.4 Connect

Click Connect.

The Inspector establishes an MCP session with the BridgeXAPI Agent Interface.

A successful connection is indicated by:

• A Connected status.

• The detected BridgeXAPI MCP server.

• A successful initialize request in the history.

• Access to the MCP interface, including Resources, Prompts and Tools.

At this point, the standard MCP initialization handshake has completed successfully.

The client is now ready to discover the capabilities exposed by the BridgeXAPI MCP server.

Step 5 — Discover the BridgeXAPI capabilities

The MCP session has now been established successfully.

At this point, no BridgeXAPI functionality has been executed.

Instead, the Inspector begins discovering the capabilities exposed by the BridgeXAPI MCP server.

Unlike traditional REST APIs, the Inspector does not have prior knowledge of the available functionality. It learns what the server exposes by performing standard MCP discovery requests.

BridgeXAPI currently exposes its functionality primarily through MCP Tools, while optional features such as Resources and Prompt Templates are not published by this implementation.

5.1 Discover Resources

Select the Resources tab and click List Resources.

The Inspector sends the standard MCP resources/list request to the BridgeXAPI MCP server.

The current BridgeXAPI implementation does not publish any static resources. This is expected because BridgeXAPI exposes executable messaging capabilities through MCP tools rather than static resources.

5.2 Discover Tools

Select the Tools tab and click List Tools.

The Inspector sends the standard MCP tools/list request to the BridgeXAPI MCP server.

The server responds with the executable capabilities currently exposed by BridgeXAPI.

Unlike a traditional REST client, the Inspector did not know these operations beforehand. The tools were discovered dynamically from the MCP server.

5.3 Inspect a Tool

After discovering the available tools, select list_routes.

The Inspector now displays the complete tool definition published by the BridgeXAPI MCP server.

For each tool, the Inspector dynamically discovers:

• the tool name

• its description

• execution characteristics

• required input parameters

• the execution interface

The Inspector did not contain any BridgeXAPI-specific logic before connecting. All of this information was obtained dynamically through the standard MCP protocol.

Step 6 — Execute Your First Tool

Until now, the Inspector has only been discovering the capabilities exposed by the BridgeXAPI MCP server.

To execute protected BridgeXAPI operations, you'll need a developer API key.

The following steps demonstrate how to obtain an API key and use it to execute your first MCP tool.

6.1 Obtain your BridgeXAPI API key

Sign in to the BridgeXAPI Developer Dashboard.

Navigate to the Developer Console, where your developer API key is available.

The API key shown below is a temporary demonstration key created exclusively for this guide. It is not activated and cannot be used to access the BridgeXAPI infrastructure.

6.2 Execute list_routes

Return to the MCP Inspector.

Select the list_routes tool.

Paste your BridgeXAPI API key into the api_key field.

The request is now fully configured and ready to be executed by the BridgeXAPI MCP server.

6.3 Review the response

Click Run Tool.

The Inspector sends a standard MCP tools/call request to the BridgeXAPI MCP server.

BridgeXAPI executes the requested operation and returns the result as structured JSON.

The response shown below contains the SMS routes currently available for the authenticated developer account, including:

• Route identifiers

• Route names

• Access policies

• Route status

• Pricing availability

• Country coverage

• Execution metadata

This is the same structured response that any MCP-compatible AI agent or client would receive when calling the list_routes tool.

6.4 Inspect the MCP request

After executing the tool, open the History panel and select the tools/call request.

The Inspector records every MCP interaction. In addition to the returned JSON response, you can inspect the exact request that was sent to the BridgeXAPI MCP server.

This request contains:

• the MCP method (tools/call)

• the selected tool (list_routes)

• the supplied arguments

• execution metadata generated by the Inspector

This is the standard MCP request structure that any compatible AI client would generate when executing the same tool.

Step 7 — Plan Message Execution

Before sending an SMS, BridgeXAPI can plan the execution.

Rather than immediately dispatching a message, the AI agent first asks the platform how the message should be executed.

The execution planner evaluates the requested delivery against the available messaging infrastructure before any SMS is submitted.

7.1 Configure the execution plan

Select plan_message_execution.

Provide:

• destination number

• message

• caller ID

• execution objective

• execution scope

• your BridgeXAPI API key

The request is now ready to be evaluated by the BridgeXAPI execution planner.

7.2 Review the execution plan

Click Run Tool.

The BridgeXAPI execution planner evaluates all eligible routes within the requested execution scope.

Rather than sending the SMS immediately, the planner returns:

• the selected execution route

• the estimated execution cost

• whether execution is ready

• the next recommended MCP tool

• the planned execution lifecycle

In this example, the planner recommends send_sms as the next operation.

7.3 Configure the SMS execution

The execution plan has now completed successfully.

Return to the send_sms tool.

Configure the message using the route recommended by the execution planner.

Provide:

• destination phone number

• message

• selected route (route_id: 1)

• caller ID

• your BridgeXAPI API key

At this point, the request is fully prepared and ready to be submitted to the BridgeXAPI messaging infrastructure.

7.4 Execute the message

Click Run Tool.

BridgeXAPI submits the message through the selected execution route.

The response returns the execution identifiers that uniquely identify this messaging operation. These identifiers are used by subsequent delivery tracking tools.

7.5 Observe delivery

Message execution does not end when the request is accepted.

After the SMS has been submitted, BridgeXAPI returns execution identifiers that allow the message to be tracked throughout its lifecycle.

The response includes identifiers such as:

• the BridgeXAPI message ID

• the order ID

• the selected execution route

• the next recommended MCP tool

These identifiers can be used with tools such as:

• get_delivery_report

• list_delivery_reports

• get_order_summary

to observe delivery progress directly from the BridgeXAPI messaging infrastructure.

Typical lifecycle states include:

• Queued

• Processing

• Sent

• Delivered

In this example, the platform recommends get_delivery_report as the next step in the execution lifecycle.

7.6 Verify the delivered message

Finally, verify that the message reached its destination.

For this guide, a public online SMS inbox is used to confirm successful delivery.

The message shown below was sent directly through the BridgeXAPI MCP server using the execution plan generated in the previous steps.

This completes the full AI-native messaging execution lifecycle:

Discover
    ↓
Plan
    ↓
Execute
    ↓
Observe
    ↓
Verify

The same execution sequence can be performed by any MCP-compatible AI agent using the BridgeXAPI MCP interface.

Conclusion

You have now completed the complete BridgeXAPI MCP discovery and execution lifecycle.

Throughout this lab you have:

• Connected to a remote BridgeXAPI MCP server

• Completed the standard MCP initialization handshake

• Discovered BridgeXAPI capabilities dynamically

• Inspected executable MCP tools

• Authenticated using a BridgeXAPI developer API key

• Planned an AI-native messaging execution

• Executed your first SMS through the BridgeXAPI messaging infrastructure

• Observed the execution lifecycle

• Verified successful message delivery

The same workflow can be performed manually through the MCP Inspector or executed autonomously by any MCP-compatible AI agent.

BridgeXAPI exposes the same programmable messaging infrastructure to both developers and AI systems.

Developers typically interact through SDKs and APIs.

AI agents interact through capability discovery, execution planning and the Model Context Protocol.

Different interfaces.

The same execution layer.

Next Steps

Now that you've completed your first BridgeXAPI MCP execution, try exploring additional capabilities exposed by the platform:

• get_balance

• get_limits

• get_route

• get_route_pricing

• estimate_sms_cost

• list_delivery_reports

• get_delivery_report

• get_order_delivery_reports

• get_order_summary

Every capability follows the same AI-native execution lifecycle demonstrated throughout this lab.