langchain-tokportal

LangChain / LangGraph integration for TokPortal.

TokPortal is the managed social infrastructure API: real TikTok, Instagram and YouTube accounts created, warmed and operated by human account managers in 16+ countries — exposed as a REST API and an MCP server. No OAuth per account, no 25-posts/day cap, no app review.

This package gives your agents two ways to drive TokPortal:

Mode	What you get	When to use
Native tools (toolkit.get_tools())	6 hand-written BaseTools wrapping the tokportal Python SDK: credit balance, create bundle, configure video, publish bundle, get bundle, list accounts	Simple sync agents, no MCP dependency at runtime
MCP tools (await toolkit.aget_tools("mcp"))	Every tool of the remote TokPortal MCP server (90+ operations: uploads, warming, analytics, webhooks, comments, bans…) loaded through langchain-mcp-adapters	Full API surface, async agents

Installation

pip install langchain-tokportal
# optional, for the LangGraph example below
pip install langchain langchain-openai

Get an API key at https://app.tokportal.com/developer and export it:

export TOKPORTAL_API_KEY=sk_...

Quick start (native tools)

from langchain_tokportal import TokPortalToolkit

toolkit = TokPortalToolkit.from_api_key()          # reads TOKPORTAL_API_KEY
tools = toolkit.get_tools()

for tool in tools:
    print(tool.name)
# tokportal_get_credit_balance
# tokportal_create_bundle
# tokportal_configure_bundle_video
# tokportal_publish_bundle
# tokportal_get_bundle
# tokportal_list_accounts

print(tools[0].invoke({}))                          # -> {"data": {"balance": ...}}

Every tool returns a JSON string (the raw TokPortal data envelope, or an {"error": {...}} object with status, code, request_id and retryable so the model can self-correct).

LangGraph agent example (langchain.agents.create_agent, LangChain 1.x)

import asyncio

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent

from langchain_tokportal import TokPortalToolkit

SYSTEM = (
    "You operate TokPortal, a managed social infrastructure API. "
    "Always check the credit balance before creating bundles. "
    "A bundle must be published for a human account manager to start working on it."
)


async def main() -> None:
    toolkit = TokPortalToolkit.from_api_key()

    # "native" = 6 SDK tools, "mcp" = full remote MCP tool set, "all" = both
    tools = await toolkit.aget_tools("mcp")

    agent = create_agent(ChatOpenAI(model="gpt-4.1"), tools, system_prompt=SYSTEM)

    result = await agent.ainvoke(
        {
            "messages": [
                (
                    "user",
                    "Order one new TikTok account in the US with 3 video slots and "
                    "advanced warming on the terms 'home workout', 'protein snacks', "
                    "'gym motivation'. Publish it and tell me the bundle id.",
                )
            ]
        }
    )
    print(result["messages"][-1].content)


asyncio.run(main())

Sync-only code paths can call toolkit.get_mcp_tools() (wraps asyncio.run).

Using the MCP connection directly

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_tokportal import mcp_connection

client = MultiServerMCPClient({"tokportal": mcp_connection("sk_...")})
tools = await client.get_tools()

mcp_connection() returns a Streamable-HTTP connection dict pointing at https://app.tokportal.com/api/ext/mcp with Authorization: Bearer <api_key>.

Tool reference (native)

Tool	REST operation
tokportal_get_credit_balance	GET /credits/balance
tokportal_create_bundle	POST /bundles
tokportal_configure_bundle_video	PUT /bundles/{id}/videos/{position}
tokportal_publish_bundle	POST /bundles/{id}/publish
tokportal_get_bundle	GET /bundles/{id}
tokportal_list_accounts	GET /accounts

Typical flow: get_credit_balance → create_bundle (draft) → configure_bundle_video × N → publish_bundle → poll get_bundle or subscribe to webhooks.

Resources

• API docs: https://developers.tokportal.com
• OpenAPI: https://developers.tokportal.com/openapi.json
• MCP server: https://developers.tokportal.com/mcp (remote https://app.tokportal.com/api/ext/mcp, stdio npx -y tokportal-mcp)
• Python SDK: https://github.com/tokportal/tokportal-python
• Support: team@tokportal.com

License

MIT