# Embedded Agent Configuration

Configuration guide for embedded AI agents used by AI-powered search tools in Sentry MCP.

## Overview

Sentry MCP uses embedded AI agents for the following tools:
- `search_events` - Natural language search across events, metrics, and session replays
- `search_issues` - Natural language search across issues
- `search_issue_events` - Search events within a specific issue
- `use_sentry` - Unified natural language interface to all Sentry operations

These tools require an LLM provider (OpenAI, Azure OpenAI, or Anthropic) to be configured.

## Provider Selection

### Explicit Configuration (Recommended)

Always set `EMBEDDED_AGENT_PROVIDER` to explicitly specify your LLM provider:

```bash
export EMBEDDED_AGENT_PROVIDER=openai   # or 'azure-openai' / 'anthropic'
export OPENAI_API_KEY=sk-...            # corresponding API key
```

> **Deprecation Notice:** Auto-detection based on API keys alone is deprecated and will be removed in a future release. Please update your configuration to explicitly set `EMBEDDED_AGENT_PROVIDER`.

### Resolution Order

Sentry MCP resolves the LLM provider in this order:

1. **Explicit configuration** (highest priority)
   - `EMBEDDED_AGENT_PROVIDER` environment variable
   - `--agent-provider` CLI flag

2. **Conflict detection**
   - If both `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` are set without explicit provider selection, an error is thrown
   - This prevents silent bugs when external tools inject API keys

3. **Auto-detection** (lowest priority, **deprecated**)
   - If only `ANTHROPIC_API_KEY` is set → use Anthropic
   - If only `OPENAI_API_KEY` is set → use OpenAI
   - A deprecation warning is logged when this fallback is used

### Configuration Methods

#### Method 1: Environment Variable (Recommended)

Set `EMBEDDED_AGENT_PROVIDER` to explicitly choose a provider:

```bash
export EMBEDDED_AGENT_PROVIDER=openai
export OPENAI_API_KEY=sk-...
```

Or:

```bash
export EMBEDDED_AGENT_PROVIDER=azure-openai
export OPENAI_API_KEY=sk-...
npx @sentry/mcp-server --openai-base-url=https://example.openai.azure.com/openai/v1/
```

Or:

```bash
export EMBEDDED_AGENT_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
```

#### Method 2: CLI Flag

```bash
npx @sentry/mcp-server --agent-provider=openai --access-token=...
```

#### Method 3: MCP Configuration File

In your MCP settings (e.g., Claude Desktop config):

```json
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "EMBEDDED_AGENT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

## Handling Conflicts with External Tools

### Problem: Claude Agent SDK Injection

When using Sentry MCP with tools like the Claude Agent SDK, the SDK may inject `ANTHROPIC_API_KEY` into the environment. This causes conflicts if you want to use OpenAI instead.

**Before (incorrect auto-detection):**
```bash
# Claude SDK injects ANTHROPIC_API_KEY
# Your MCP config only sets OPENAI_API_KEY
# Result: Sentry MCP incorrectly uses Anthropic
```

**After (explicit provider selection):**
```bash
# Claude SDK injects ANTHROPIC_API_KEY
# Your MCP config sets OPENAI_API_KEY and EMBEDDED_AGENT_PROVIDER=openai
# Result: Sentry MCP correctly uses OpenAI
```

### Solution

Always set `EMBEDDED_AGENT_PROVIDER` when multiple API keys might be present:

```json
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "EMBEDDED_AGENT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

## Error Messages

### "Both API keys are set"

```
Error: Both ANTHROPIC_API_KEY and OPENAI_API_KEY are set.
Please specify which provider to use by setting the EMBEDDED_AGENT_PROVIDER
environment variable to 'openai', 'azure-openai', or 'anthropic'.
```

**Cause:** Multiple API keys detected without explicit provider selection.

**Solution:** Set `EMBEDDED_AGENT_PROVIDER` to choose which provider to use.

### "Provider configured but API key not set"

```
Error: Provider "openai" is configured but OPENAI_API_KEY is not set.
Please set the API key environment variable.
```

**Cause:** Explicit provider selected but corresponding API key is missing.

**Solution:** Set the required API key environment variable.

### "No embedded agent provider configured"

```
Error: No embedded agent provider configured.
Set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable,
or use --agent-provider flag to specify a provider.
```

**Cause:** No API keys found and no provider specified.

**Solution:** Set at least one API key environment variable.

## Advanced Configuration

### Custom Base URLs

For custom OpenAI-compatible endpoints or Anthropic proxies:

```bash
export EMBEDDED_AGENT_PROVIDER=openai
export OPENAI_API_KEY=sk-...
npx @sentry/mcp-server --openai-base-url=https://custom.openai.example.com
```

For Azure OpenAI or Azure-compatible deployment proxies, use the dedicated
provider instead of the generic `openai` mode:

```bash
export EMBEDDED_AGENT_PROVIDER=azure-openai
export OPENAI_API_KEY=sk-...
export OPENAI_API_VERSION=2024-02-15-preview

# Azure v1 endpoint -> Responses API
npx @sentry/mcp-server --openai-base-url=https://example.openai.azure.com/openai/v1/

# Deployment endpoint -> chat completions
npx @sentry/mcp-server --openai-base-url=https://example.openai.azure.com/openai/deployments/my-assistant
```

### Model Selection

Override the default model for each provider:

```bash
# OpenAI (default: gpt-5)
export OPENAI_MODEL=gpt-4

# Anthropic (default: claude-opus-4-5-20251101)
export ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
```

### Verify Configuration

Check which provider is being used:

```bash
npx @sentry/mcp-server --access-token=... 2>&1 | grep "Using"
```

Expected output:
```
Using openai responses API for AI-powered search tools (from EMBEDDED_AGENT_PROVIDER).
```

Or:
```
Using anthropic for AI-powered search tools (auto-detected).
```

## Troubleshooting

### Provider not detected

**Check environment variables:**
```bash
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $EMBEDDED_AGENT_PROVIDER
```

**Verify API key format:**
- OpenAI: `sk-...` (starts with `sk-`)
- Anthropic: `sk-ant-...` (starts with `sk-ant-`)

### External tool conflicts

If external tools (like Claude SDK, LangChain, etc.) inject API keys:

1. Use `EMBEDDED_AGENT_PROVIDER` to override auto-detection
2. Consider using a wrapper script to filter environment variables
3. Report the issue to the external tool's maintainers

### Testing provider selection

Test with both API keys present:

```bash
export ANTHROPIC_API_KEY=sk-ant-test
export OPENAI_API_KEY=sk-test
export EMBEDDED_AGENT_PROVIDER=openai

npx @sentry/mcp-server --access-token=...
```

Should output:
```
Using openai responses API for AI-powered search tools (from EMBEDDED_AGENT_PROVIDER).
```

## Related Documentation

- [Security](./security.md) - Authentication and token management
- [Testing](./testing.md) - Testing MCP server functionality
- [Common Patterns](./common-patterns.md) - Error handling and response formatting