# Give an OpenAI Agents SDK, LangChain or n8n agent a NZ number

> Point your framework's MCP client at Agentline NZ's remote server, https://agentline.nz/mcp, and send an API key as Authorization: Bearer al_live_…. In the OpenAI Agents SDK that's MCPServerStreamableHttp, in LangChain and LangGraph it's MCPAdapter with a FastMCP Client, and in n8n it's the MCP Client Tool node with Bearer Auth. The agent then has its own New Zealand 028 number and @agentline.nz inbox. The inbox is live from day one; the number is set up within a few days of signup.

Updated 2026-10-20 · https://agentline.nz/guides/openai-agents-sdk-langchain-n8n-nz-number

## Before you start

- **An API key.** Create one in the dashboard under API keys (it starts `al_live_` and is shown once) and export it as `AGENTLINE_KEY`. Each key counts as one connected agent. OAuth works too, but a key is simpler for code and workflows.
- **A plan.** Start free with an email inbox (no card), or take a 7-day trial of Starter or Pro to get a number. Starter is NZ$29/month and Pro is NZ$79/month.
- **Timing.** The inbox works from day one. The NZ 028 number is set up within a few days of signup, and you get an email when it's live. Until then, `send_sms` returns `number_pending`. If the number hasn't arrived within 30 days of your first payment, you can ask for a full refund.
- **No account yet?** An agent can create one itself. See [agent self-signup](https://agentline.nz/guides/agent-self-signup).

## What the agent gets

The same tools as any other MCP client: `get_my_number`, `send_sms`, `list_messages`, `read_message`, `send_email`, `list_emails`, `read_email`, `mark_read`, `wait_for_code` and, on Pro, `list_calls`. The [tool reference](https://agentline.nz/docs#mcp) has the full list. With an API key, `wait_for_code` returns the code itself, so the agent can finish a sign-up on its own.

## Set the timeout to 60 seconds

`wait_for_code` waits up to 55 seconds (45 by default) for a code and looks back 10 minutes by default. If it returns `found: false`, call it again. Each code is returned once. The tool call stays open while it waits, so the client's timeout has to be longer than that wait:

- **OpenAI Agents SDK:** `client_session_timeout_seconds` is how long the SDK waits for a tool result, and it defaults to 5 seconds, so set it to 60. `params.timeout` only covers connecting and sending the request; 60 is fine there too.
- **LangChain:** pass `timeout=60` to the FastMCP `Client`.
- **n8n:** the MCP Client Tool's Timeout option defaults to 60000 ms, which is enough.

## OpenAI Agents SDK (Python)

```bash
pip install openai-agents
```

```python
import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="agentline",
        params={
            "url": "https://agentline.nz/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['AGENTLINE_KEY']}"},
            "timeout": 60,
        },
        client_session_timeout_seconds=60,
        cache_tools_list=True,
    ) as agentline:
        agent = Agent(
            name="Assistant",
            instructions="Use Agentline NZ to text, email and wait for one-time codes.",
            mcp_servers=[agentline],
        )
        result = await Runner.run(agent, "What's my Agentline NZ number and email address?")
        print(result.final_output)

asyncio.run(main())
```

To keep an agent read-only, pass `tool_filter=create_static_tool_filter(allowed_tool_names=["get_my_number", "list_messages", "list_emails", "read_email", "wait_for_code"])` (import it from `agents.mcp`). The JavaScript SDK has the same `MCPServerStreamableHttp` class; there's a sample on the [OpenAI Agents SDK integration page](https://agentline.nz/integrations/openai-agents-sdk).

**HostedMCPTool**, where OpenAI's Responses API calls the server instead of your process, isn't covered in this guide, and we haven't tested it. This guide uses `MCPServerStreamableHttp` with the key.

## LangChain and LangGraph (Python)

LangChain now ships MCP support as `langchain.mcp`, which replaces the separate `langchain-mcp-adapters` package and its `MultiServerMCPClient`. It needs `langchain[mcp]` 1.4 or later, and it's in beta, so it raises a `LangChainBetaWarning`.

```bash
pip install "langchain[mcp]>=1.4.0"
```

```python
import asyncio, os
from fastmcp.client import Client
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

async def main():
    client = Client("https://agentline.nz/mcp", auth=os.environ["AGENTLINE_KEY"], timeout=60)
    async with MCPAdapter(client) as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5", tools)
        result = await agent.ainvoke(
            {"messages": [{"role": "user", "content": "What's my Agentline NZ number and email address?"}]}
        )
        print(result["messages"][-1].content)

asyncio.run(main())
```

A string passed as `auth` is sent as `Authorization: Bearer`. `create_agent` runs on LangGraph and replaces LangGraph's `create_react_agent`, so this is also the LangGraph setup. Use any chat model your install supports. More detail is on the [LangChain integration page](https://agentline.nz/integrations/langchain).

## n8n

1. On your **AI Agent** node, add a tool and choose **MCP Client Tool**.
2. Set **Endpoint** to `https://agentline.nz/mcp` and **Server Transport** to **HTTP Streamable**.
3. Set **Authentication** to **Bearer Auth** and create a credential with your key as the **Bearer Token**. **MCP OAuth2** also works if you'd rather sign in.
4. Under **Tools to Include**, pick **All**, or **Selected** to limit the agent, for example to `list_messages` and `wait_for_code`.

If the node shows **SSE Endpoint** instead of **Endpoint**, it's an old version of the node that only speaks SSE, which Agentline NZ doesn't serve. Add a new MCP Client Tool node instead. For a fixed step without an AI Agent, such as "send this confirmation text", the **MCP Client** node runs one tool. See the [n8n integration page](https://agentline.nz/integrations/n8n).

## Using the REST API instead

The same features are on the REST API at `https://agentline.nz/api/v1`, with the same `Authorization: Bearer` header, so you can wrap a few calls as your framework's own function tools or use n8n's HTTP Request node:

```bash
curl -X POST https://agentline.nz/api/v1/sms \
  -H "Authorization: Bearer $AGENTLINE_KEY" -H "Content-Type: application/json" \
  -d '{"to":"021 123 4567","body":"Your booking is confirmed for 3pm Thursday."}'
```

The main endpoints are `GET /me`, `POST /sms`, `GET /sms`, `POST /emails`, `GET /emails` and `POST /wait-for-code`. Each key can make 120 requests a minute. The [OpenAPI spec](https://agentline.nz/openapi.json) covers the rest.

## Limits to build around

- New accounts can message only the owner's verified email and mobile until they're on a paid plan; anything else returns `recipient_not_allowed`.
- SMS goes to NZ mobiles only (020/021/022/027/028/029), and only transactional, one-to-one messages are allowed. Marketing and bulk texts are blocked. See [the UEMA and agents](https://agentline.nz/guides/nz-uema-ai-agents).
- Some services won't send verification codes to business messaging numbers. Test the ones you rely on.

For coding tools such as Cursor, VS Code and Claude Code, see [adding Agentline NZ to developer tools](https://agentline.nz/guides/add-sms-to-cursor-vscode-claude-code).

## Steps

1. **Create an API key.** In the Agentline NZ dashboard, open API keys, create one and export it as AGENTLINE_KEY. It's shown once.
2. **Connect your framework.** Use MCPServerStreamableHttp (OpenAI Agents SDK), MCPAdapter with a FastMCP Client (LangChain and LangGraph) or the MCP Client Tool node (n8n), with https://agentline.nz/mcp and the key as a Bearer token.
3. **Allow 60 seconds per tool call.** wait_for_code can wait up to 55 seconds, so set the client's timeout to 60 seconds.
4. **Check it works.** Ask the agent: What's my Agentline NZ number and email address? It should call get_my_number.

## Common questions

### Can I use the OpenAI Agents SDK's HostedMCPTool with Agentline NZ?

It isn't covered in this guide. HostedMCPTool has OpenAI's Responses API call the server instead of your process, and we haven't tested that route. This guide uses MCPServerStreamableHttp with your API key in the Authorization header.

### Do I still need langchain-mcp-adapters?

No. LangChain's langchain.mcp namespace (langchain[mcp] 1.4 or later) replaces it. Wrap a FastMCP Client with your key as auth in MCPAdapter and pass adapter.list_tools() to create_agent.

### Can the agent read one-time codes?

Yes. With an API key, wait_for_code returns the code from an SMS or email. It waits up to 55 seconds, so give the client a 60-second timeout, and each code is returned once.

### How long does it take to get the number?

The email inbox works from day one. The NZ 028 number is set up within a few days of signup, and you get an email when it's live. If it hasn't arrived within 30 days of your first payment, you can ask for a full refund.