Give an OpenAI Agents SDK, LangChain or n8n agent a 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.

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 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)

pip install openai-agents

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.

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.

pip install "langchain[mcp]>=1.4.0"

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.

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.

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:

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 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.
• 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.

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

Related guides

• Add SMS and email tools to Cursor, VS Code and Claude Code
• How an AI agent can sign itself up for Agentline
• How to give an AI agent a New Zealand phone number