How to Build and Test AI Agents That Call External APIs

How an MCP agent calls an external API

The Model Context Protocol, or MCP, is a protocol for connecting AI applications to servers that provide tools, resources, and prompts. It is useful when you want a host application to discover capabilities at runtime instead of embedding every tool implementation directly into the agent.

MCP compatibility belongs primarily to the host and its MCP client implementation, not directly to the language model. A model may support tool use, but something in the host application still has to maintain the MCP connection, discover the server's tools, present appropriate tool definitions to the model, execute approved calls, and return the results to the reasoning loop.

The complete request path in this tutorial looks like this:

User prompt
    |
    v
LangChain agent and MCP host
    |
    | MCP initialization, tools/list, tools/call
    | over Streamable HTTP
    v
Public Localtonet HTTPS endpoint
    |
    | outbound tunnel connection
    v
Local FastMCP server at 127.0.0.1:8000/mcp
    |
    | ordinary outbound HTTPS requests
    v
Weather and exchange-rate REST APIs

The two protocol layers must not be confused. The MCP client does not discover tools by sending an ordinary GET /mcp/tools/list request, and it does not call a tool by posting to /mcp/tools/call. Streamable HTTP carries MCP JSON-RPC messages. A client begins with MCP initialization and capability negotiation, then sends protocol methods such as tool discovery and tool invocation through the negotiated connection.

Streamable HTTP and stdio are different transports

With the stdio transport, the MCP host launches the server as a local child process and exchanges protocol messages through standard input and output. This is appropriate when the host and server run on the same machine and the host supports local process configuration.

With Streamable HTTP, the server listens on an HTTP endpoint and the MCP client connects to a URL. This is the relevant transport when the host runs on another machine or in cloud infrastructure. The protocol concepts are consistent across transports, but configuration and lifecycle code are not identical. Stdio requires a command, arguments, environment, and child-process management. Streamable HTTP requires a URL, HTTP behavior, and any applicable authorization or session headers.

Prerequisites and project environment

You need Python, a package installer, outbound internet access for the example APIs, and a Localtonet client for the machine that will run the tunnel. The exact Python versions supported by FastMCP, the MCP Python SDK, LangChain, and the adapter can change. Before adopting this example in an existing project, check the current package metadata and use a Python release supported by all installed packages.

You will also need credentials for the model provider used by the LangChain example. This tutorial uses the langchain-openai integration, so the agent process expects an OpenAI API key and a model identifier. The weather and exchange-rate tools themselves do not read that model-provider credential.

Create and activate a virtual environment

Start in an empty project directory. On macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

On Windows PowerShell:

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

Install the server and client dependencies

python -m pip install fastmcp httpx langchain-mcp-adapters langchain langchain-openai python-dotenv

Package interfaces evolve. Once the server, protocol client, and agent pass your tests together, record the exact resolved environment:

python -m pip freeze > requirements.lock

A teammate or CI job can then recreate that tested environment with:

python -m pip install -r requirements.lock

Build a FastMCP server with reliable API handling

The server below exposes two tools. get_weather accepts explicit latitude and longitude values, while convert_currency accepts an amount and two three-letter currency codes. Requiring coordinates avoids a hidden reliability gap: a city name cannot be passed to a coordinate-only tool unless you also implement a geocoding tool.

The implementation validates tool inputs before making outbound requests. It also sets an HTTP timeout, checks HTTP status codes, validates the expected response structure, and returns useful failures without disclosing an upstream response body.

# server.py
import math
import re
from typing import Any

import httpx
from fastmcp import FastMCP

mcp = FastMCP("External API Tools")

HTTP_TIMEOUT = httpx.Timeout(10.0, connect=5.0)
CURRENCY_CODE = re.compile(r"^[A-Za-z]{3}$")

async def fetch_json(
    client: httpx.AsyncClient,
    url: str,
    *,
    params: dict[str, Any] | None = None,
) -> dict[str, Any]:
    try:
        response = await client.get(url, params=params)
        response.raise_for_status()
    except httpx.TimeoutException as exc:
        raise RuntimeError("The upstream API timed out.") from exc
    except httpx.HTTPStatusError as exc:
        raise RuntimeError(
            f"The upstream API returned HTTP {exc.response.status_code}."
        ) from exc
    except httpx.RequestError as exc:
        raise RuntimeError("The upstream API could not be reached.") from exc

    try:
        payload = response.json()
    except ValueError as exc:
        raise RuntimeError("The upstream API returned invalid JSON.") from exc

    if not isinstance(payload, dict):
        raise RuntimeError("The upstream API returned an unexpected response.")

    return payload

@mcp.tool()
async def get_weather(latitude: float, longitude: float) -> dict[str, Any]:
    """Get current weather for explicit latitude and longitude coordinates."""
    if not math.isfinite(latitude) or not -90 <= latitude <= 90:
        raise ValueError("latitude must be a finite number from -90 to 90.")

    if not math.isfinite(longitude) or not -180 <= longitude <= 180:
        raise ValueError("longitude must be a finite number from -180 to 180.")

    params = {
        "latitude": latitude,
        "longitude": longitude,
        "current": "temperature_2m,wind_speed_10m,weather_code",
        "temperature_unit": "celsius",
    }

    async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
        payload = await fetch_json(
            client,
            "https://api.open-meteo.com/v1/forecast",
            params=params,
        )

    current = payload.get("current")
    if not isinstance(current, dict):
        raise RuntimeError("The weather API response has no current conditions.")

    required = ("temperature_2m", "wind_speed_10m", "weather_code")
    if any(name not in current for name in required):
        raise RuntimeError("The weather API response is missing required fields.")

    return {
        "latitude": latitude,
        "longitude": longitude,
        "temperature_celsius": current["temperature_2m"],
        "wind_speed": current["wind_speed_10m"],
        "weather_code": current["weather_code"],
    }

@mcp.tool()
async def convert_currency(
    amount: float,
    from_currency: str,
    to_currency: str,
) -> dict[str, Any]:
    """Convert a non-negative amount using the latest available exchange rate."""
    if not math.isfinite(amount) or amount < 0:
        raise ValueError("amount must be a finite, non-negative number.")

    if not CURRENCY_CODE.fullmatch(from_currency):
        raise ValueError("from_currency must be a three-letter currency code.")

    if not CURRENCY_CODE.fullmatch(to_currency):
        raise ValueError("to_currency must be a three-letter currency code.")

    source = from_currency.upper()
    target = to_currency.upper()

    async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
        payload = await fetch_json(
            client,
            f"https://open.er-api.com/v6/latest/{source}",
        )

    if payload.get("result") != "success":
        raise RuntimeError("The exchange-rate API rejected the request.")

    rates = payload.get("rates")
    if not isinstance(rates, dict):
        raise RuntimeError("The exchange-rate response has no rates object.")

    rate = rates.get(target)
    if not isinstance(rate, (int, float)) or not math.isfinite(rate) or rate <= 0:
        raise ValueError(f"No valid exchange rate was returned for {target}.")

    return {
        "from": source,
        "to": target,
        "amount": amount,
        "rate": rate,
        "converted": round(amount * rate, 4),
    }

if __name__ == "__main__":
    mcp.run(transport="http", host="127.0.0.1", port=8000)

Start the server:

python server.py

Leave this process running. Stop it cleanly with Ctrl+C when testing is complete. If the process exits, the local MCP endpoint stops immediately, even if a tunnel configuration still exists.

Verify the server with an initialized MCP client

Test the MCP layer before adding an agent or a public tunnel. This isolates protocol and tool failures from model behavior and network forwarding. A successful test should initialize the session, list both tools, and invoke them with known valid arguments.

Option 1: Use a small Python MCP client

Save the following as verify_mcp.py. It uses the MCP SDK's Streamable HTTP client rather than constructing REST-like requests.

# verify_mcp.py
import asyncio

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

MCP_URL = "http://127.0.0.1:8000/mcp"

async def main() -> None:
    async with streamablehttp_client(MCP_URL) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            tools = await session.list_tools()
            print("Available tools:")
            for tool in tools.tools:
                print(f"- {tool.name}: {tool.description}")

            weather = await session.call_tool(
                "get_weather",
                arguments={
                    "latitude": 41.0082,
                    "longitude": 28.9784,
                },
            )
            print("\nWeather result:")
            print(weather.content)

            conversion = await session.call_tool(
                "convert_currency",
                arguments={
                    "amount": 100,
                    "from_currency": "USD",
                    "to_currency": "EUR",
                },
            )
            print("\nCurrency result:")
            print(conversion.content)

if __name__ == "__main__":
    asyncio.run(main())

With server.py still running in another terminal, execute:

python verify_mcp.py

Confirm that the client discovers get_weather and convert_currency, then inspect both tool results. Live values will vary. A protocol exception at initialization usually indicates a wrong path, incompatible transport, server startup failure, or package-version mismatch. A tool exception after successful discovery usually points to invalid arguments or an upstream API problem.

Option 2: Use the MCP Inspector

The MCP Inspector is useful when you want an interactive protocol-aware interface. Launch the current Inspector according to its package instructions, choose Streamable HTTP, and connect to http://127.0.0.1:8000/mcp. Initialize the connection before listing or calling tools.

Inspector startup commands and browser behavior can change between releases, so use the command documented by the installed Inspector version rather than copying an old global-install command. The important requirement is that the tool performs MCP initialization and sends proper MCP messages, not plain REST requests.

Test invalid and failure cases deliberately

Successful calls are not enough. Try a latitude outside -90 to 90, a malformed currency code such as US, and a negative conversion amount. The server should reject each input before contacting an upstream service. You should also understand how the client displays tool errors so an agent cannot mistake an error string for valid data.

Secure the MCP server before public exposure

The example server does not implement application-level authentication. Once an HTTP tunnel is started, its public endpoint can receive traffic from outside your machine. A hard-to-guess URL is not a substitute for authorization, and sharing the URL broadly expands the audience that can attempt tool calls.

Prompt injection does not stop at the prompt

An agent may retrieve text from an external API and feed it back into the model. That content can contain instructions designed to alter the agent's behavior. Keep data and instructions conceptually separate, restrict which tools the agent can call, require confirmation for consequential actions, and enforce permissions in code rather than trusting the model to obey a policy described only in a prompt.

Keep secrets out of tools and logs

Model-provider keys belong in the agent environment, while credentials needed by a tool belong in the server environment. Do not return those values from a tool. Do not include them in exception messages, tunnel URLs, screenshots, source control, or debug output. If a credential is accidentally exposed, revoke and replace it rather than merely deleting it from the latest commit.

Expose the MCP endpoint with a Localtonet HTTP tunnel

After local protocol verification succeeds, an ordinary Localtonet HTTP tunnel can forward the public HTTPS path to the Streamable HTTP server on 127.0.0.1:8000. The Localtonet client establishes an outbound connection to our relay, so this workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.

Creating a tunnel configuration does not start it. The selected Localtonet client must be connected and the tunnel must be running. If the local server, Localtonet client, or tunnel stops, the public MCP endpoint becomes unavailable.

If the assigned address were https://your-assigned-host.example, the MCP URL supplied to a Streamable HTTP client would be:

https://your-assigned-host.example/mcp

That hostname is intentionally illustrative, not a real Localtonet endpoint. Always use the exact public address assigned to your running tunnel.

Verify the tunnel without changing the protocol

In verify_mcp.py, change only the URL:

MCP_URL = "https://your-assigned-host.example/mcp"

Run the same verification script. This repeats initialization, discovery, and tool calls through the public route. It tests the complete chain from the MCP client to the relay, through the outbound tunnel, into FastMCP, and onward to each external API.

Connect the remote MCP server to a LangChain agent

Once public protocol verification succeeds, use the LangChain MCP adapter to load the server's tools. The adapter configuration must identify the transport as streamable_http. Using the generic value http in this client configuration can cause a transport mismatch.

The server accepts coordinates, not city names. The test prompt therefore includes explicit coordinates for Istanbul. If you want users to ask for weather by city, add a separately validated geocoding tool or perform geocoding in another trusted application layer.

Store model credentials outside source code

Create a local .env file:

OPENAI_API_KEY=replace_with_your_real_key
OPENAI_MODEL=replace_with_a_tool_capable_model_identifier
MCP_SERVER_URL=https://your-assigned-host.example/mcp

Add .env to .gitignore before entering a real key:

printf "\n.env\n" >> .gitignore

Create the agent

Save this as agent.py:

# agent.py
import asyncio
import os

from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI

load_dotenv()

def required_environment(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Required environment variable {name} is missing.")
    return value

async def main() -> None:
    mcp_url = required_environment("MCP_SERVER_URL")
    model_name = required_environment("OPENAI_MODEL")
    required_environment("OPENAI_API_KEY")

    client = MultiServerMCPClient(
        {
            "external-api-tools": {
                "url": mcp_url,
                "transport": "streamable_http",
            }
        }
    )

    tools = await client.get_tools()
    if not tools:
        raise RuntimeError("The MCP server returned no tools.")

    model = ChatOpenAI(model=model_name)
    agent = create_agent(model=model, tools=tools)

    result = await agent.ainvoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "Get the current weather for latitude 41.0082 "
                        "and longitude 28.9784. Then convert 100 USD "
                        "to EUR. State which coordinates and currencies "
                        "you used, and do not invent missing tool data."
                    ),
                }
            ]
        }
    )

    print(result["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

Make sure all three processes or services are available in the correct order:

1. The FastMCP server is running on 127.0.0.1:8000.
2. The selected Localtonet client is connected and the HTTP tunnel is running.
3. The public MCP URL in MCP_SERVER_URL includes the /mcp path.

Then run:

python agent.py

The adapter initializes an MCP connection and obtains tool definitions. The agent can then decide whether to call the weather and currency tools. The model does not independently connect to Localtonet or speak MCP. The host-side LangChain and adapter code performs those operations.

Testing and routine operation

Test each layer independently before relying on an end-to-end agent result. This makes failures attributable. If the direct Python MCP client fails, changing the model prompt is unlikely to help. If direct calls succeed but the agent chooses the wrong tool, investigate tool descriptions, prompt design, model capability, and agent policy.

Development logging

Log tool name, request identifier, duration, outcome category, and sanitized error information. Avoid logging full authorization headers, API keys, user prompts, personal information, or complete third-party payloads by default. Structured logs make it easier to distinguish validation failures from network timeouts and upstream HTTP errors.

Starting a test session

1. Activate the tested virtual environment.
2. Start server.py and verify it locally with the MCP client.
3. Run the Localtonet client and confirm the selected device is connected.
4. Start the existing HTTP tunnel or create one using the documented workflow.
5. Verify the public MCP URL with the protocol-aware client.
6. Run the LangChain agent only after those checks pass.

Ending a test session

1. Stop agent jobs and remote test clients.
2. Stop the Localtonet tunnel so the public endpoint is no longer available.
3. Delete the tunnel if it is not intended for reuse.
4. Stop the local FastMCP process with Ctrl+C.
5. Review logs for leaked secrets or unexpected calls and rotate any exposed credential.

Client compatibility and deployment decisions

Do not assume that every application advertising MCP support accepts every MCP transport or remote-server configuration. Some hosts support only locally launched stdio servers. Others support Streamable HTTP but require a specific connector, authorization flow, deployment policy, or user interface.

Before configuring a desktop assistant, editor, automation platform, or hosted agent, verify all of the following in that product's current primary documentation:

• Whether remote Streamable HTTP MCP servers are supported.
• How remote server URLs are registered.
• Whether authentication headers or an authorization flow can be configured.
• How the host handles MCP sessions, redirects, timeouts, and reconnects.
• Whether administrators must enable remote tools.
• How users review and approve consequential tool calls.

A local stdio configuration file cannot automatically be converted into a remote HTTP configuration by replacing a command with a URL. The transport, process lifecycle, credential handling, and host support differ. For that reason, this tutorial does not provide a universal Claude Desktop, editor, or automation-platform configuration.

Localtonet is not categorically limited to development, and this article does not make that claim. The concrete availability condition is that a tunnel remains reachable only while the selected Localtonet client or device is connected and the tunnel is running. Evaluate that lifecycle together with your application's authentication, monitoring, recovery, capacity, data handling, and operational requirements.

Troubleshooting MCP, API, and tunnel failures

Use layer-by-layer diagnosis

Start with the first failing boundary. Confirm the server process, then local MCP initialization, then local tool calls, then the connected Localtonet client, then the running public tunnel, then public MCP calls, and finally the agent. Skipping directly to prompt changes can hide a basic path or transport error.

Be careful with retries

A weather lookup is naturally read-only, but many real MCP tools create records, send messages, charge accounts, or modify infrastructure. Automatic retries can duplicate those actions. Before adding retry logic, classify the operation, use idempotency controls where the external API supports them, cap attempts, and log the final outcome without leaking sensitive data.

Frequently asked questions