Upsonic
Build autonomous AI agents in Python.
What is Upsonic?
Upsonic is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to build autonomous ai agents in python.
Build autonomous AI agents in Python.
This server falls under the Coding Agents category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Build autonomous AI agents in Python.
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx upsonicConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Upsonic
Upsonic is a Python framework for building autonomous and traditional AI agents that can perform complex, multi-step tasks using any LLM provider including Claude, OpenAI, and Gemini. It supports prebuilt community agents, custom tool creation with the @tool decorator, MCP tool integration, and a built-in OCR pipeline for document processing. Developers use it to orchestrate agentic workflows in Python with workspace-sandboxed file and shell operations, making it easy to go from idea to running agent in seconds.
Prerequisites
- Python 3.10+ installed
- uv or pip package manager
- An API key for at least one LLM provider (e.g. ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for OpenAI)
- An MCP-compatible client such as Claude Desktop or Cursor
- Optional: E2B account for sandboxed cloud execution environments
Install Upsonic via pip or uv
Install the Upsonic Python package using uv (recommended for speed) or pip. Optionally install the OCR extras if you plan to process documents.
uv pip install upsonic
# or with OCR support:
uv pip install "upsonic[ocr]"Set your LLM provider API key
Upsonic delegates LLM calls to your chosen provider. Export the appropriate key as an environment variable before running any agent.
export ANTHROPIC_API_KEY="your-anthropic-api-key"
# or for OpenAI:
export OPENAI_API_KEY="your-openai-api-key"Create a traditional agent with a task
Write a Python script that instantiates an Agent and a Task, then calls agent.print_do(task) to run it interactively in the terminal.
from upsonic import Agent, Task
agent = Agent(model="anthropic/claude-sonnet-4-5", name="My Agent")
task = Task(description="Summarize the top trends in AI this week")
agent.print_do(task)Build an autonomous agent with a workspace
Use AutonomousAgent when you need file system and shell access. All operations are restricted to the specified workspace path to prevent path traversal.
from upsonic import AutonomousAgent, Task
agent = AutonomousAgent(
model="anthropic/claude-sonnet-4-5",
workspace="/path/to/workspace"
)
task = Task("Analyze server logs and detect anomaly patterns")
agent.print_do(task)Add custom tools with the @tool decorator
Decorate any Python function with @tool to expose it to your agent. Pass the tool in the Task's tools list.
from upsonic import Agent, Task
from upsonic.tools import tool
@tool
def get_word_count(text: str) -> int:
"""Count words in text."""
return len(text.split())
task = Task(description="Count words in 'Hello World'", tools=[get_word_count])
agent = Agent(model="anthropic/claude-sonnet-4-5", name="Word Counter")
agent.print_do(task)Configure MCP client to launch via npx
Add Upsonic to your Claude Desktop or Cursor MCP configuration so it can be invoked as an MCP server.
Index Upsonic docs in your IDE for better autocomplete
In Cursor, go to Settings → Indexing & Docs and add the Upsonic LLM-friendly docs URL so the AI assistant has full API context.
https://docs.upsonic.ai/llms-full.txtUpsonic Examples
Client configuration
Claude Desktop config to launch Upsonic as an MCP server via npx.
{
"mcpServers": {
"upsonic": {
"command": "npx",
"args": ["upsonic"],
"env": {
"ANTHROPIC_API_KEY": "your-anthropic-api-key"
}
}
}
}Prompts to try
Example tasks you can give to an Upsonic agent once it is running.
- "Analyze the files in my workspace and list any TODO comments"
- "Search for the latest Python packaging best practices and write a summary"
- "Read invoice.pdf and extract the total amount due"
- "Monitor my server logs directory and alert if ERROR count exceeds 10 per minute"
- "Create a stock analyst report for AAPL using current market trends"Troubleshooting Upsonic
ModuleNotFoundError when importing upsonic
Ensure you are in the correct virtual environment. Run `uv pip install upsonic` or `pip install upsonic` inside the activated environment, then verify with `python -c 'import upsonic'`.
Agent hangs or returns empty response
Verify the LLM provider API key is set correctly in the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.). Check network connectivity and confirm your account has API quota remaining.
AutonomousAgent blocked from accessing a file path
Upsonic sandboxes all file and shell operations to the workspace directory. Ensure the files you want to access are inside the path passed to the `workspace` argument of AutonomousAgent.
Frequently Asked Questions about Upsonic
What is Upsonic?
Upsonic is a Model Context Protocol (MCP) server that build autonomous ai agents in python. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Upsonic?
Follow the installation instructions on the Upsonic GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Upsonic?
Upsonic works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Upsonic free to use?
Yes, Upsonic is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Upsonic Alternatives — Similar Coding Agents Servers
Looking for alternatives to Upsonic? Here are other popular coding agents servers you can use with Claude, Cursor, and VS Code.
Dify
★ 142.2kProduction-ready platform for agentic workflow development.
Ruflo
★ 54.0k🌊 The leading agent orchestration platform for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features enterprise-grade architecture, self-learning swarm intelligence, RAG integrat
Goose
★ 45.7kan open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM
Antigravity Awesome Skills
★ 38.3kInstallable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
AgentScope
★ 25.5kBuild and run agents you can see, understand and trust.
Serena
★ 24.5kA coding agent toolkit that provides IDE-like semantic code retrieval and editing tools, enabling LLMs to efficiently navigate and modify codebases using symbol-level operations instead of basic file reading and string replacements.
Browse More Coding Agents MCP Servers
Explore all coding agents servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Upsonic in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Upsonic?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.