langchain-surgemesh

LangChain tools for Surgemesh, agent-first social publishing. Your agent can quote the exact price of a post, schedule it to one or more social channels, check its prepaid credit, and track delivery, all through one API key.

Preview: quotes, channel connects and sandbox posts work today. Sandbox posts are validated against each network's real limits and priced exactly, but never published or charged. Live posting and payments are coming soon.

Install

pip install langchain-surgemesh

Get an API key

curl -X POST https://api.surgemesh.com/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email": "you@example.com", "accept_terms": true}'

The response holds your api_key (shown once). Then:

export SURGEMESH_API_KEY=sm_...

Quick start

from langchain.agents import create_agent
from langchain_surgemesh import SurgemeshToolkit

toolkit = SurgemeshToolkit()            # reads SURGEMESH_API_KEY
agent = create_agent("openai:gpt-4.1", toolkit.get_tools())

agent.invoke({"messages": "List my Surgemesh channels, quote a post for 2026-11-03T15:00:00Z, "
                          "then schedule 'Hello from our agent' to my sandbox channel at that time."})

Tools

You can also use each tool on its own: SurgemeshQuotePostTool, SurgemeshPublishPostTool, SurgemeshListChannelsTool, SurgemeshGetBalanceTool, SurgemeshGetPostStatusTool. Use the toolkit when you want publish_post to accept a quote_id from quote_post; tools created by one toolkit share their quotes.

Safety rules built in

• Nothing posts on its own. The tools act only when your agent calls them. Installing the package or building the toolkit makes no requests.
• Quote first. publish_post refuses to run without a quote_id from quote_post or an explicit idempotency_key. With a quote_id, the quoted price becomes the post's price cap (max_price_usd), so the post is refused rather than charged more.
• Exactly once. Every publish carries an idempotency key, so a retry never double-posts or double-charges. A quote_id is used for one post.
• Clear credit errors. If the account lacks prepaid credit, the tool says so plainly (nothing is scheduled or charged) and points to cheaper times or adding credit.

To ask a person before anything is published, put publish_post behind your framework's human-in-the-loop step.

Configuration

toolkit = SurgemeshToolkit.from_api_key(api_key="sm_...", base_url="https://api.surgemesh.com")

Errors raise SurgemeshError (with status, code and hint); InsufficientCreditError and QuoteRequiredError are subclasses. Inside an agent, tools return the error message to the model instead of crashing the run.

Zero-code alternative: the Surgemesh MCP server

Surgemesh is also a remote MCP server (com.surgemesh/surgemesh in the MCP Registry) with the full tool set, including channel connect, onboarding and analytics. With langchain-mcp-adapters:

import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent

client = MultiServerMCPClient({
    "surgemesh": {
        "transport": "streamable_http",
        "url": "https://api.surgemesh.com/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['SURGEMESH_API_KEY']}"},
    }
})
tools = await client.get_tools()
agent = create_agent("openai:gpt-4.1", tools)

Use this package when you want a small, typed tool set with the quote-first guard; use MCP when you want every Surgemesh tool.

Links

• Website: https://surgemesh.com
• API reference (OpenAPI): https://api.surgemesh.com/openapi.json
• Agent guide: https://surgemesh.com/agents
• Terms: https://surgemesh.com/terms · Privacy: https://surgemesh.com/privacy

License

Apache License 2.0. Copyright 2026 Novus Index, LLC. See LICENSE and NOTICE. "Surgemesh" is a trademark of Novus Index, LLC; the license grants no trademark rights (see TRADEMARKS.md in the repository root). Contact: dev@surgemesh.com