OSS Setup (Open Source / Local SDK)

OSS Setup (Open Source / Local SDK)

This guide covers using Airbyte Agent Connectors directly via the Python SDK without platform integration. Use this approach when you want to run connectors locally with your own credential management.

Contents

• When to Use OSS Mode
• Installation
• Basic Usage
• OAuth Connectors (Local Mode)
• Environment Setup
• MCP Server Setup for Claude
• Agent Framework Integration
• Credential Security Best Practices
• Common Operations Quick Reference
• Troubleshooting
• Setup Workflow
• Related Documentation

When to Use OSS Mode

Use OSS Mode when you want:

• Quick development and prototyping
• Self-hosted deployments
• Single-tenant applications
• Direct control over credentials
• No dependency on Airbyte Cloud
• Claude Code/Desktop integration via MCP

Installation

Install connectors individually based on the services you need:

# Using uv (recommended)
uv add airbyte-agent-github
uv add airbyte-agent-stripe
uv add airbyte-agent-salesforce

# Or using pip in a virtual environment
python3 -m venv .venv && source .venv/bin/activate
pip install airbyte-agent-github
pip install airbyte-agent-stripe
pip install airbyte-agent-salesforce

Note: When working in the airbyte-agent-connectors repo, packages are already available—no installation needed.

All connectors follow the naming pattern airbyte-agent-{service}.

Basic Usage

API Key Connectors

import asyncio
import os
from dotenv import load_dotenv
from airbyte_agent_stripe import StripeConnector
from airbyte_agent_stripe.models import StripeAuthConfig

load_dotenv()

async def main():
    connector = StripeConnector(
        auth_config=StripeAuthConfig(api_key=os.environ["STRIPE_API_KEY"])
    )

    result = await connector.execute("customers", "list", {"limit": 10})
    for customer in result.data:
        print(f"{customer['id']}: {customer.get('email', 'No email')}")

asyncio.run(main())

GitHub with Personal Access Token

from airbyte_agent_github import GithubConnector
from airbyte_agent_github.models import GithubPersonalAccessTokenAuthConfig

connector = GithubConnector(
    auth_config=GithubPersonalAccessTokenAuthConfig(
        token=os.environ["GITHUB_TOKEN"]
    )
)

# List repositories
result = await connector.execute("repositories", "list", {
    "username": "octocat",
    "per_page": 10
})

Gong with API Key

from airbyte_agent_gong import GongConnector
from airbyte_agent_gong.models import GongAccessKeyAuthenticationAuthConfig

connector = GongConnector(
    auth_config=GongAccessKeyAuthenticationAuthConfig(
        access_key=os.environ["GONG_ACCESS_KEY"],
        access_key_secret=os.environ["GONG_ACCESS_KEY_SECRET"]
    )
)

# List calls
result = await connector.execute("calls", "list", {})

Slack with Bot Token

from airbyte_agent_slack import SlackConnector
from airbyte_agent_slack.models import SlackAuthConfig

connector = SlackConnector(
    auth_config=SlackAuthConfig(token=os.environ["SLACK_BOT_TOKEN"])
)

# List channels
result = await connector.execute("channels", "list", {})

HubSpot with Private App Token

from airbyte_agent_hubspot import HubspotConnector
from airbyte_agent_hubspot.models import HubspotPrivateAppAuthConfig

connector = HubspotConnector(
    auth_config=HubspotPrivateAppAuthConfig(
        access_token=os.environ["HUBSPOT_ACCESS_TOKEN"]
    )
)

# List contacts
result = await connector.execute("contacts", "list", {"limit": 100})

OAuth Connectors (Local Mode)

For OAuth connectors in OSS Mode, you need to handle the OAuth flow yourself and provide the tokens directly:

Salesforce with OAuth

from airbyte_agent_salesforce import SalesforceConnector
from airbyte_agent_salesforce.models import SalesforceOAuthConfig

connector = SalesforceConnector(
    auth_config=SalesforceOAuthConfig(
        client_id=os.environ["SALESFORCE_CLIENT_ID"],
        client_secret=os.environ["SALESFORCE_CLIENT_SECRET"],
        refresh_token=os.environ["SALESFORCE_REFRESH_TOKEN"]
    )
)

# The connector handles token refresh automatically
result = await connector.execute("accounts", "list", {"limit": 50})

HubSpot with OAuth

from airbyte_agent_hubspot import HubspotConnector
from airbyte_agent_hubspot.models import HubspotOAuthConfig

connector = HubspotConnector(
    auth_config=HubspotOAuthConfig(
        client_id=os.environ["HUBSPOT_CLIENT_ID"],
        client_secret=os.environ["HUBSPOT_CLIENT_SECRET"],
        refresh_token=os.environ["HUBSPOT_REFRESH_TOKEN"]
    )
)

Environment Setup

Create a .env file in your project root:

# GitHub (Personal Access Token)
GITHUB_TOKEN=ghp_your_token_here

# Stripe (API Key)
STRIPE_API_KEY=sk_live_your_key_here

# Gong (API Key pair)
GONG_ACCESS_KEY=your_access_key
GONG_ACCESS_KEY_SECRET=your_access_key_secret

# Slack (Bot Token)
SLACK_BOT_TOKEN=xoxb-your-token

# HubSpot (Private App Token)
HUBSPOT_ACCESS_TOKEN=pat-na1-xxx

# Jira (API Token)
JIRA_API_TOKEN=your_api_token
JIRA_EMAIL=your_email@example.com
JIRA_DOMAIN=your-domain.atlassian.net

# Salesforce (OAuth - requires completing OAuth flow first)
SALESFORCE_CLIENT_ID=your_client_id
SALESFORCE_CLIENT_SECRET=your_client_secret
SALESFORCE_REFRESH_TOKEN=your_refresh_token

MCP Server Setup for Claude

Expose your connectors to Claude Code or Claude Desktop via MCP.

Step 1: Configure Connectors

Create configured_connectors.yaml in the airbyte-agent-mcp directory:

connectors:
  # Stripe - API Key
  - id: stripe
    type: local
    connector_name: stripe
    description: "Stripe payment processing"
    secrets:
      api_key: STRIPE_API_KEY

  # GitHub - Personal Access Token
  - id: github
    type: local
    connector_name: github
    description: "GitHub repositories and issues"
    secrets:
      token: GITHUB_TOKEN

  # Gong - API Key pair
  - id: gong
    type: local
    connector_name: gong
    description: "Gong conversation intelligence"
    secrets:
      access_key: GONG_ACCESS_KEY
      access_key_secret: GONG_ACCESS_KEY_SECRET

  # Slack - Bot Token
  - id: slack
    type: local
    connector_name: slack
    description: "Slack messaging"
    secrets:
      token: SLACK_BOT_TOKEN

Step 2: Create .env File

Create .env in the airbyte-agent-mcp directory with your credentials:

STRIPE_API_KEY=sk_live_...
GITHUB_TOKEN=ghp_...
GONG_ACCESS_KEY=...
GONG_ACCESS_KEY_SECRET=...
SLACK_BOT_TOKEN=xoxb-...

Step 3: Add to Claude Code

cd /path/to/your/project
claude mcp add airbyte-agent-mcp --scope project

When prompted, provide the server configuration:

{
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/airbyte-agent-connectors/airbyte-agent-mcp",
    "run",
    "airbyte_agent_mcp"
  ]
}

Step 4: Add to Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "airbyte-agent-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/airbyte-agent-connectors/airbyte-agent-mcp",
        "run",
        "airbyte_agent_mcp"
      ]
    }
  }
}

Restart Claude Desktop after making changes.

Agent Framework Integration

PydanticAI

from pydantic_ai import Agent
from airbyte_agent_github import GithubConnector
from airbyte_agent_github.models import GithubPersonalAccessTokenAuthConfig

connector = GithubConnector(
    auth_config=GithubPersonalAccessTokenAuthConfig(token=os.environ["GITHUB_TOKEN"])
)

agent = Agent("openai:gpt-4o", system_prompt="You help with GitHub data.")

@agent.tool_plain
async def list_issues(owner: str, repo: str, limit: int = 10) -> str:
    """List open issues in a repository."""
    result = await connector.execute("issues", "list", {
        "owner": owner,
        "repo": repo,
        "states": ["OPEN"],
        "per_page": limit
    })
    return str(result.data)

@agent.tool_plain
async def get_repository(owner: str, repo: str) -> str:
    """Get repository details."""
    result = await connector.execute("repositories", "get", {
        "owner": owner,
        "repo": repo
    })
    return str(result.data)

LangChain

from langchain.tools import StructuredTool
import asyncio

# For sync contexts, wrap the async call properly
def execute_sync(entity: str, action: str, params: dict):
    """Wrapper for async connector.execute() in sync context."""
    loop = asyncio.get_event_loop()
    return loop.run_until_complete(connector.execute(entity, action, params))

github_tool = StructuredTool.from_function(
    func=execute_sync,
    name="github",
    description="Execute GitHub operations"
)

Note: If you're already in an async context (e.g., inside an async function), use LangChain's async tool support or call connector.execute() directly with await.

Credential Security Best Practices

Development

• Use .env files (add to .gitignore)
• Use test/sandbox credentials when possible

Production

• Use secret managers (AWS Secrets Manager, HashiCorp Vault)
• Never commit credentials to version control
• Rotate credentials regularly

# AWS Secrets Manager example
import boto3
import json

def get_secret(secret_name: str) -> dict:
    client = boto3.client("secretsmanager")
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response["SecretString"])

secrets = get_secret("my-app/stripe")
connector = StripeConnector(
    auth_config=StripeAuthConfig(api_key=secrets["api_key"])
)

Common Operations Quick Reference

# List operations
await connector.execute("customers", "list", {"limit": 10})
await connector.execute("issues", "list", {"owner": "org", "repo": "name", "states": ["OPEN"]})

# Get operations
await connector.execute("customers", "get", {"id": "cus_xxx"})
await connector.execute("repositories", "get", {"owner": "org", "repo": "name"})

# Search operations
await connector.execute("repositories", "api_search", {"query": "language:python stars:>1000"})
await connector.execute("customers", "api_search", {"query": "email:'user@example.com'"})

# Create operations (where supported)
await connector.execute("customers", "create", {"email": "user@example.com", "name": "Jane"})

Troubleshooting

"ModuleNotFoundError"

• Ensure the connector package is installed: pip install airbyte-agent-{connector}

"401 Unauthorized"

• Verify credentials are correct and not expired
• Check token scopes/permissions

"RuntimeWarning: coroutine was never awaited"

• Always use await with connector.execute()
• Run in async context with asyncio.run(main())

MCP Server not starting

• Verify uv is installed: uv --version
• Check paths in configuration are correct
• Test manually: cd airbyte-agent-mcp && uv run airbyte_agent_mcp

Setup Workflow

OSS User: "Set up a [Connector] connector"

1. Ask for connector credentials (e.g., GitHub token, Stripe API key)
2. Guide local SDK usage:

   from airbyte_agent_github import GithubConnector
   from airbyte_agent_github.models import GithubPersonalAccessTokenAuthConfig
   
   connector = GithubConnector(
       auth_config=GithubPersonalAccessTokenAuthConfig(token="ghp_...")
   )
   

3. Optionally: Guide MCP server setup for Claude integration

Related Documentation

• Platform Setup - Hosted mode with UI visibility
• MCP Integration - Detailed MCP server configuration
• Authentication - Auth patterns by connector
• Entity-Action API - Core API patterns
• Troubleshooting - Common errors and solutions