Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Configure authentication for MCP servers that require credentials.

​
Usage

from upsonic import Task, Agent
from upsonic.tools.mcp import MCPHandler

# MCP server with authentication
auth_handler = MCPHandler(
    command="npx -y @company/private-mcp-server",
    env={
        "API_KEY": "your_api_key_here",
        "API_SECRET": "your_api_secret_here",
        "AUTH_TOKEN": "bearer_token_here"
    },
    timeout_seconds=60
)

# Multiple servers with different auth
github_handler = MCPHandler(
    command="npx -y @modelcontextprotocol/server-github",
    env={
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
    },
    timeout_seconds=60
)

slack_handler = MCPHandler(
    command="uvx mcp-server-slack",
    env={
        "SLACK_BOT_TOKEN": "xoxb-xxxxx",
        "SLACK_TEAM_ID": "T1234567"
    },
    timeout_seconds=60
)

# Create task with authenticated tools
task = Task(
    description="Fetch the latest open issues from the repository 'my-project/repo' using the GitHub tool, then send a summary of these issues to the '#dev-team' channel on Slack.",
    tools=[github_handler, slack_handler]
)

# Create agent
agent = Agent(
    name="Integration Agent",
    model="anthropic/claude-sonnet-4-5"
)

# Execute
result = agent.print_do(task)
print("Result:", result)

​
Parameters

  • command (str): Command string to run MCP server
  • url (str): URL for SSE or Streamable HTTP transport
  • env (Dict[str, str]): Dictionary of environment variables for authentication
    • Common keys: API_KEY, API_SECRET, AUTH_TOKEN, ACCESS_TOKEN
    • Service-specific keys: GITHUB_PERSONAL_ACCESS_TOKEN, SLACK_BOT_TOKEN, etc.
  • timeout_seconds (int): Connection timeout in seconds (default: 5)

​
Best Practices

  • Store credentials securely (use environment variables or secrets management)
  • Never hardcode credentials in source code
  • Use separate credentials for development and production
  • Rotate credentials regularly
  • Follow the principle of least privilege

​
Example with Environment Variables

import os
from upsonic import Task, Agent
from upsonic.tools.mcp import MCPHandler

# Load from environment
secure_handler = MCPHandler(
    command="npx -y @company/mcp-server",
    env={
        "API_KEY": os.getenv("MCP_API_KEY"),
        "API_SECRET": os.getenv("MCP_API_SECRET")
    },
    timeout_seconds=60
)

task = Task(
    description="Connect to the secure company MCP server and retrieve the latest confidential report.",
    tools=[secure_handler]
)

agent = Agent(name="Secure Agent", model="anthropic/claude-sonnet-4-5")
result = agent.print_do(task)
print("Result:", result)

​
SSE Server Authentication

Use SSEClientParams to pass authentication headers to an SSE MCP server: 
from upsonic import Task, Agent
from upsonic.tools.mcp import MCPHandler

# SSE server with authentication
sse_handler = MCPHandler(
    url="https://mcp-server.com/sse",
    timeout_seconds=60
)

task = Task(
    description="Connect to the real-time SSE MCP server and listen for the latest status updates.",
    tools=[sse_handler]
)

agent = Agent(name="SSE Agent", model="anthropic/claude-sonnet-4-5")
result = agent.print_do(task)
print("Result:", result)

​
Streamable HTTP Authentication

Use StreamableHTTPClientParams to pass authentication headers to a Streamable HTTP MCP server: 
from datetime import timedelta
from upsonic import Task, Agent
from upsonic.tools.mcp import MCPHandler, StreamableHTTPClientParams

http_handler = MCPHandler(
    server_params=StreamableHTTPClientParams(
        url="https://mcp-server.com/mcp",
        headers={"Authorization": "Bearer your-api-token"},
        timeout=timedelta(seconds=30),
        sse_read_timeout=timedelta(seconds=120)
    ),
    timeout_seconds=60
)

task = Task(
    description="Connect to the authenticated HTTP MCP server and retrieve the latest data.",
    tools=[http_handler]
)

agent = Agent(name="HTTP Agent", model="anthropic/claude-sonnet-4-5")
result = agent.print_do(task)
print("Result:", result)

​
Troubleshooting Authentication

Common authentication issues:
  • Invalid credentials: Verify tokens and keys are correct
  • Expired tokens: Refresh or regenerate authentication tokens
  • Permission errors: Ensure credentials have required scopes/permissions
  • Network errors: Check firewall and proxy settings for authenticated connections