LinkedIn profiles in the OpenAI Agents SDK: a LinkedIn tool through MCP or @function_tool

• Python 3.10 or later, which the SDK needs.
• The SDK: pip install openai-agents. It installs requests, which the function uses, and the mcp package, which the MCP code uses.
• A Datacircle API key: Log in at datacircle.dev/login with your work email. Your API key is on the page once you're in. Put it in DATACIRCLE_API_KEY. You get a $5 credit, enough for 2,105 profiles through Up2Data.
• An OpenAI API key in OPENAI_API_KEY. The code names no model, so the SDK uses its default model, gpt-5.6-luna. Pass model= to the Agent to choose another.

The SDK connects to a remote MCP server with MCPServerStreamableHttp, as its MCP page shows, and the agent takes the server in mcp_servers. Our MCP server is at https://api.datacircle.dev/mcp. It gets a LinkedIn profile from its URL, through Up2Data, HarvestAPI or Fetchin. The SDK doesn't sign you in to a server by itself, and our server reads your key from Authorization, so the key goes in headers as a Bearer token. This file is the whole agent:

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter


async def main():
    async with MCPServerStreamableHttp(
        name="datacircle",
        params={
            "url": "https://api.datacircle.dev/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['DATACIRCLE_API_KEY']}"},
        },
        client_session_timeout_seconds=60,
        tool_filter=create_static_tool_filter(allowed_tool_names=["get_linkedin_profile"]),
    ) as server:
        agent = Agent(
            name="Profile researcher",
            instructions="Answer questions about the current role on a LinkedIn profile. Get the profile with get_linkedin_profile.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "What is the current job title on https://www.linkedin.com/in/williamhgates?")
        print(result.final_output)


asyncio.run(main())

MCPServerStreamableHttp connects over Streamable HTTP, the transport our server uses. client_session_timeout_seconds is how long the SDK waits for a tool's answer: 5 seconds by default, and our API waits up to 45 seconds for the provider. With the default, our test server took 7 seconds to answer, and the model got "An error occurred while running the tool. Please try again." The server has other tools, such as get_balance, and the filter keeps get_linkedin_profile alone. The model sees it under that name: the SDK puts the server's name before it only if you set include_server_in_tool_names.

The tool takes url, and provider: up2data (the default), harvestapi or fetchin. It returns the provider's whole JSON, every job and school included, plus datacircle_meta: what the call cost and your balance after it. On a failed call, the model gets our API's error JSON, and the run goes on. At Up2Data's limit, the server tells your agent to call again through Fetchin or HarvestAPI. The model picks which one, and HarvestAPI costs more per 1,000 profiles than the other two. Our MCP server docs list every tool.

A wrong key stops the async with block before the SDK calls the model, with MCPError: invalid API key or access token. With an mcp package older than 2, it's UserError: Failed to connect to MCP server 'datacircle': HTTP error 401.

HostedMCPTool: OpenAI's servers call ours

You can also use HostedMCPTool, if your agent runs on an OpenAI model through the Responses API. We haven't tested it: it needs a real OpenAI model, so this part comes from OpenAI's docs alone. OpenAI's servers list and call our tools, so your key goes to OpenAI with each request. OpenAI's API reference gives the tool two fields for this: headers, HTTP headers to send to the MCP server "for authentication or other purposes", and authorization, for "an OAuth access token". Neither the reference nor OpenAI's MCP guide says in what form OpenAI sends authorization to the server. Our server reads your key from an Authorization: Bearer <your key> header, which you can put in headers. The guide says the Responses API doesn't store authorization, and says nothing about headers.

In tool_config, set server_url to our URL, allowed_tools to get_linkedin_profile and require_approval to "never": by default, OpenAI asks for your approval before each call to an MCP server. If you store the response, OpenAI logs what it sends to our server for 30 days, unless your organization has Zero Data Retention.

You send the provider's own request to api.datacircle.dev, with your Datacircle key. That's the only change. The function sends Up2Data's own request, with X-Data-Provider naming the provider. Save the code below as datacircle_tool.py:

import json
import os
import time

import requests
from agents import function_tool

API = os.environ.get("DATACIRCLE_API_URL", "https://api.datacircle.dev")
KEY = os.environ["DATACIRCLE_API_KEY"]


def call(provider, method, path, **request):
    """One call to Datacircle's API through one provider. Fetchin's 429 is its rate limit: wait a second and send it again."""
    for wait in (0, 1, 2):
        time.sleep(wait)
        answer = requests.request(method, f"{API}{path}", headers={"Authorization": f"Token {KEY}", "X-Data-Provider": provider}, timeout=60, **request)
        if provider != "fetchin" or answer.status_code != 429:
            return answer
    return answer


@function_tool(failure_error_function=None)
def get_linkedin_profile(url: str) -> str:
    """Get the current job title, company, location and headline on a LinkedIn profile, from the profile's URL,
    like https://www.linkedin.com/in/williamhgates. Each call asks the provider live and is billed to the Datacircle balance."""
    answer = call("up2data", "POST", "/v1/profiles/enrich", json={"url": url})
    if answer.status_code == 200:
        profile = answer.json()["data"]
        company = profile.get("current_company") or {}
        return json.dumps({"job_title": company.get("title"), "company": company.get("name"),
                           "location": (profile.get("location") or {}).get("raw"), "headline": profile.get("headline")})
    if answer.status_code == 429:  # Up2Data's daily limit: Fetchin answers instead
        answer = call("fetchin", "GET", "/api/v1/profile", params={"profileUrlOrUrn": url})
        if answer.status_code == 200:
            profile = answer.json()
            return json.dumps({"job_title": profile.get("jobTitle"), "company": profile.get("companyName"),
                               "location": profile.get("location"), "headline": profile.get("title")})
    if answer.status_code in (404, 422):
        return "This LinkedIn profile is private or deleted."
    if answer.status_code == 400:
        return "This is not a LinkedIn profile URL. Send one like https://www.linkedin.com/in/williamhgates"
    if answer.status_code == 402:
        return "The Datacircle balance is too low for this call. Tell the user to add funds on their Datacircle dashboard."
    if answer.status_code in (429, 500, 502, 503, 504):
        return f"The provider didn't answer ({answer.status_code}), and the call wasn't charged. Try again in a minute."
    answer.raise_for_status()  # 401: DATACIRCLE_API_KEY is wrong, and the run stops

The SDK's @function_tool decorator turns the function into a tool: the function's name is the tool's, its docstring is the description the model reads, and the type hint on url is its input. OpenAI's newer examples import it as tool, from agents.decorators, where the SDK's code makes tool another name for function_tool. The function sends the URL to Up2Data. At Up2Data's daily limit (its 429), it sends the same URL to Fetchin. Fetchin takes 5 requests a second from all our customers together, and returns a 429 past that: the function waits one second and sends it again, then waits two seconds and sends it once more.

The model gets four fields back, as JSON text:

{"job_title": …, "company": …, "location": …, "headline": …}

The function returns text, not a dict: the SDK passes a dict to the model through Python's str(), and in our test it came out with single quotes, which isn't JSON. For a private or deleted profile, a URL that isn't a profile, a low balance or a provider error, the tool returns a sentence instead, so the agent can tell the user and go on.

failure_error_function=None is for a wrong key (401). By default, when a tool raises, the SDK tells the model "An error occurred while running the tool. Please try again." and, in our test, printed nothing else. With None, the error stops the run: UserError: Error running tool get_linkedin_profile: 401 Client Error: Unauthorized. Set the right key in DATACIRCLE_API_KEY. Each field comes from the same JSON path as in our Python post:

DATACIRCLE_API_URL is for tests: point it at a mock of our API, and you can run the tool without spending your balance. We tested the tool against one.

An Agent gets a name, instructions and its tools, and the Runner runs the loop: the model asks for a tool, reads the tool's answer, and replies. Runner.run_sync runs Runner.run for you, in a script with no event loop. With the @function_tool function:

from agents import Agent, Runner

from datacircle_tool import get_linkedin_profile

agent = Agent(
    name="Profile researcher",
    instructions="Answer questions about the current role on a LinkedIn profile. Get the profile with get_linkedin_profile.",
    tools=[get_linkedin_profile],
)
result = Runner.run_sync(agent, "What is the current job title on https://www.linkedin.com/in/williamhgates?")
print(result.final_output)

The answer is in result.final_output. The MCP example above builds the same agent, with mcp_servers where this one has tools, and await Runner.run inside main().

Up2Data takes $1 a day per account (421 profiles), with a shared daily limit for all customers, then answers 429 until 00:00 UTC. HarvestAPI has no daily limit. Fetchin has no daily limit either.

• We ran these tests on October 11, 2026, on Python 3.12, with openai-agents 0.23.1 and the mcp 2.3.0 and requests 2.34.2 it installs.
• Each Python file above ran unchanged, through Runner.run or Runner.run_sync. Our test code pointed the MCP agent's URL at a stand-in server, without editing the file. The model was a scripted stand-in: a Model of our own, in place of OpenAI's, that asks for get_linkedin_profile once, then answers with what the tool returned.
• The agent and its function ran against a stand-in server on our machine that answers like our API: the example 200 answers for Up2Data and Fetchin from our API reference, then each error in the table. Each time, the model got what the table lists for that answer.
• The MCP agent ran against a stand-in that answers like our MCP server: the SDK listed get_linkedin_profile and called it, and our errors reached the model without stopping the run. With client_session_timeout_seconds left at 5, an answer that took 7 seconds reached the model as an error.
• We called api.datacircle.dev with a wrong key. Our API answered the function with a 401 and {"error": "invalid api key"}, and the run stopped with UserError. The MCP agent stopped at MCPError: invalid API key or access token. These calls cost nothing.
• We didn't run HostedMCPTool, or any test with a real Datacircle key or a real model.

We charge your balance the prices on our pricing page, with no markup:

Say your agent looks up 1,000 profiles in a day with the @function_tool function, one call each, and the providers find every one. You pay us at most $1.86: $1.00 for 421 through Up2Data and $0.86 for the other 579 through Fetchin. An agent may call the tool more than once for a question, and we bill each call. OpenAI bills you for the model's tokens.

The same tool for a LangChain agent: LinkedIn profiles in LangChain. For a CrewAI crew: LinkedIn profiles in CrewAI. In TypeScript, with Vercel's AI SDK: LinkedIn profiles in the Vercel AI SDK. For a LlamaIndex agent: LinkedIn profiles in LlamaIndex. The same call from a Python script: get LinkedIn profile data with Python. In an n8n workflow: LinkedIn profiles in n8n. In Claude, ChatGPT or Cursor: our LinkedIn MCP server. Other vendors' prices per 1,000: LinkedIn profile API pricing compared.