# BridgeXAPI MCP Discovery Lab: Your First AI-Native Messaging Execution # 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: ```text /screenshots ``` ## Step 1 — Verify Node.js ```bash node -v npm -v ``` ![Node version](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/39ad1da1-f4be-4e1c-a3a4-ac019eaf705d.png align="center") ## Step 2 — Start the MCP Inspector Launch the official Model Context Protocol Inspector using `npx`. ```bash 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: ![Starting the MCP Inspector](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/d89bc230-596f-4b36-aedf-8641ce4460e0.png align="center") 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: ```text 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: ![MCP Inspector Home](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/b3c7e202-e968-4b27-8291-958d8c1c02fb.png align="center") 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: ```text Streamable HTTP ``` ![Select Streamable HTTP](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/1abf4a88-cfa5-49b2-aa46-c376fc7d8638.png align="center") * * * ### 4.2 Configure the BridgeXAPI MCP endpoint Now configure the MCP server you want the Inspector to connect to. Enter the BridgeXAPI MCP endpoint: ```text 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. ![BridgeXAPI MCP Connection Configuration](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/5c448de2-762e-45da-af49-6363a44ead05.png align="center") * * * ### 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. ![Authentication Panel](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/18f760dd-02af-4d7e-a759-31f6f9a0bf3e.png align="center") * * * ### 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. ![Connected to BridgeXAPI MCP](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/760f23a9-94d0-465c-a8eb-6255d8931c61.png align="center") 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. ![BridgeXAPI Resources](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/396dd09c-c698-4b5b-ab8d-655f0d93e56b.png align="center") * * * ## 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. ![BridgeXAPI Tools List](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/626b656c-8178-4c9c-b679-d9eae2a90f7e.png align="center") * * * ### 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. ![Inspect list_routes](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/a98e3e83-d8e9-433d-96be-58191f834f8b.png align="center") * * * # 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. ![BridgeXAPI Developer Console](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/02f130c8-76d9-410d-9283-5d0c407cf043.png align="center") * * * ### 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. ![list_routes with API key](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/81051c99-9931-430c-b3a3-b608aed517e9.png align="center") * * * ### 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. ![list_routes response](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/e772e123-13d5-4668-b624-c8859c0a8940.png align="center") * * * * * * * * * ### 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. ![MCP tools/call request](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/6bd34d6b-fd76-490a-bf40-bcb0178efa71.png align="center") * * * # 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. ![Plan Message Execution](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/5e89baa1-9abc-47b0-bd78-0aef4165d852.png align="center") * * * ### 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. ![Execution plan result](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/ff7c8ec6-84f5-41db-86ec-35dff2ed80f1.png align="center") * * * ### 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. ![Send SMS configuration](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/cc6637b4-606d-478c-afe9-f6c3ae400be9.png align="center") * * * ### 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. ![Send SMS response](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/22b400fb-41a0-4523-ba6f-4c8d0910844d.png align="center") * * * ### 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: ```text Discover ↓ Plan ↓ Execute ↓ Observe ↓ Verify ``` The same execution sequence can be performed by any MCP-compatible AI agent using the BridgeXAPI MCP interface. ![SMS received](https://cdn.hashnode.com/uploads/covers/69cc48c9e4688e4edd4ebae0/5b44b476-5d84-407e-bd95-3412f180abe9.png align="center") * * * ## 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.