> ## 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.

# Authentication

> Configure authentication for MCP servers that require credentials

## Overview

Configure authentication for MCP servers that require credentials.

## Usage

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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