> ## Documentation Index
> Fetch the complete documentation index at: https://bundleup.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby

## Installation

Install the SDK using Bundler or RubyGems:

**Using Bundler (recommended):**

Add this line to your application's Gemfile:

```ruby theme={null}
gem 'bundleup-sdk'
```

And then execute:

```bash theme={null}
bundle install
```

**Using RubyGems:**

```bash theme={null}
gem install bundleup-sdk
```

## Requirements

* **Ruby**: 2.7.0 or higher
* **Faraday**: \~> 2.0 (automatically installed as a dependency)

### Ruby Compatibility

The BundleUp SDK is tested and supported on:

* Ruby 2.7.x
* Ruby 3.0.x
* Ruby 3.1.x
* Ruby 3.2.x
* Ruby 3.3.x

## Features

* 🚀 **Ruby Idiomatic** - Follows Ruby best practices and conventions
* 📦 **Easy Integration** - Simple, intuitive API design
* ⚡ **HTTP/2 Support** - Built on Faraday for modern HTTP features
* 🔌 **100+ Integrations** - Connect to Slack, GitHub, Jira, Linear, and many more
* 🎯 **Unified API** - Consistent interface across all integrations via the Unified API
* 🔑 **Proxy API** - Direct access to underlying integration APIs
* 🤖 **MCP** - Hand a connection to any MCP client, or to OpenAI and Anthropic's hosted MCP
* 🪶 **Lightweight** - Minimal dependencies
* 🛡️ **Error Handling** - Comprehensive error messages and validation
* 📚 **Well Documented** - Extensive documentation and examples
* 🧪 **Tested** - Comprehensive test suite with RSpec

## Quick Start

Get started with BundleUp in just a few lines of code:

```ruby theme={null}
require 'bundleup'

# Initialize the client
client = BundleUp::Client.new(ENV['BUNDLEUP_API_KEY'])

# List all active connections
connections = client.connections.list
puts "You have #{connections.length} active connections"

# Use the Proxy API to make requests to integrated services
proxy = client.proxy('conn_123')
response = proxy.get('/api/users')
puts "Users: #{response.body}"

# Use the Unified API for standardized data across integrations
unify = client.unify('conn_456')
channels = unify.chat.channels(limit: 10)
puts "Chat channels: #{channels['data']}"
```

## Authentication

The BundleUp SDK uses API keys for authentication. You can obtain your API key from the [BundleUp Dashboard](https://app.bundleup.io).

### Getting Your API Key

1. Sign in to your [BundleUp Dashboard](https://app.bundleup.io)
2. Navigate to **API Keys**
3. Click **Create API Key**
4. Copy your API key and store it securely

### Initializing the SDK

```ruby theme={null}
require 'bundleup'

# Initialize with API key
client = BundleUp::Client.new('your_api_key_here')

# Or use environment variable (recommended)
client = BundleUp::Client.new(ENV['BUNDLEUP_API_KEY'])
```

### Security Best Practices

* ✅ **DO** store API keys in environment variables
* ✅ **DO** use a secrets management service in production
* ✅ **DO** rotate API keys regularly
* ❌ **DON'T** commit API keys to version control
* ❌ **DON'T** hardcode API keys in your source code
* ❌ **DON'T** share API keys in public channels

**`Example .env file:`**

```bash theme={null}
BUNDLEUP_API_KEY=Zw7Lt7...
```

**Loading environment variables (using dotenv):**

Add to your Gemfile:

```ruby theme={null}
gem 'dotenv'
```

Then in your application:

```ruby theme={null}
require 'dotenv/load'
require 'bundleup'

client = BundleUp::Client.new(ENV['BUNDLEUP_API_KEY'])
```

**For Rails applications:**

```ruby theme={null}
# config/initializers/bundleup.rb
BUNDLEUP_CLIENT = BundleUp::Client.new(ENV['BUNDLEUP_API_KEY'])
```

## Core Concepts

### Auth API

The **Auth API** runs the hosted authorization flow: build the URL that sends a user to connect an integration, then exchange the one-time `code` from the redirect for a `connection_id`. See [Authorization Flow](/docs/guides/auth/authorization-flow).

### Platform API

The **Platform API** provides access to core BundleUp features like managing connections and integrations. Use this API to list, retrieve, and delete connections, as well as discover available integrations.

### Proxy API

The **Proxy API** allows you to make direct HTTP requests to the underlying integration's API through BundleUp. This is useful when you need access to integration-specific features not covered by the Unified API.

### Unified API

The **Unified API** provides a standardized, normalized interface across different integrations. For example, you can fetch chat channels from Slack or Discord using the same API call.

### MCP API

The **MCP API** reaches a provider's own MCP server using a connection's stored credentials. Tools are defined by the provider, not by BundleUp. Because the connection is chosen per client, one agent can serve many end users without ever handling a token. See [MCP overview](/docs/guides/mcp/overview).

## API Reference

### Connections

Manage your integration connections.

#### List Connections

Retrieve a list of all connections in your account.

```ruby theme={null}
connections = client.connections.list
```

**With query parameters:**

```ruby theme={null}
connections = client.connections.list(
  integration_id: 'int_slack',
  limit: 50,
  offset: 0,
  external_id: 'user_123'
)
```

**Query Parameters:**

* `integration_id` (String): Filter by integration ID
* `integration_identifier` (String): Filter by integration identifier (e.g., 'slack', 'github')
* `external_id` (String): Filter by external user/account ID
* `limit` (Integer): Maximum number of results (default: 50, max: 100)
* `offset` (Integer): Number of results to skip for pagination

**Response:**

```ruby theme={null}
[
  {
    'id' => 'conn_123abc',
    'external_id' => 'user_456',
    'integration_id' => 'int_slack',
    'created_at' => '2024-01-15T10:30:00Z',
    'updated_at' => '2024-01-20T14:22:00Z',
    'expires_at' => '2024-04-20T14:22:00Z'
  },
  # ... more connections
]
```

#### Retrieve a Connection

Get details of a specific connection by ID.

```ruby theme={null}
connection = client.connections.retrieve('conn_123abc')
```

**Response:**

```ruby theme={null}
{
  'id' => 'conn_123abc',
  'external_id' => 'user_456',
  'integration_id' => 'int_slack',
  'created_at' => '2024-01-15T10:30:00Z',
  'updated_at' => '2024-01-20T14:22:00Z',
  'expires_at' => '2024-04-20T14:22:00Z'
}
```

#### Delete a Connection

Remove a connection from your account.

```ruby theme={null}
client.connections.delete('conn_123abc')
```

**Note:** Deleting a connection will revoke access to the integration and cannot be undone.

### Integrations

Discover and work with available integrations.

#### List Integrations

Get a list of all available integrations.

```ruby theme={null}
integrations = client.integrations.list
```

**With query parameters:**

```ruby theme={null}
integrations = client.integrations.list(
  status: 'active',
  limit: 100,
  offset: 0
)
```

**Query Parameters:**

* `status` (String): Filter by status ('active', 'inactive', 'beta')
* `limit` (Integer): Maximum number of results
* `offset` (Integer): Number of results to skip for pagination

**Response:**

```ruby theme={null}
[
  {
    'id' => 'int_slack',
    'identifier' => 'slack',
    'name' => 'Slack',
    'category' => 'chat',
    'created_at' => '2023-01-01T00:00:00Z',
    'updated_at' => '2024-01-15T10:00:00Z'
  },
  # ... more integrations
]
```

#### Retrieve an Integration

Get details of a specific integration.

```ruby theme={null}
integration = client.integrations.retrieve('int_slack')
```

**Response:**

```ruby theme={null}
{
  'id' => 'int_slack',
  'identifier' => 'slack',
  'name' => 'Slack',
  'category' => 'chat',
  'created_at' => '2023-01-01T00:00:00Z',
  'updated_at' => '2024-01-15T10:00:00Z'
}
```

### Webhooks

Manage webhook subscriptions for real-time event notifications.

#### List Webhooks

Get all registered webhooks.

```ruby theme={null}
webhooks = client.webhooks.list
```

**With pagination:**

```ruby theme={null}
webhooks = client.webhooks.list(
  limit: 50,
  offset: 0
)
```

**Response:**

```ruby theme={null}
[
  {
    'id' => 'webhook_123',
    'name' => 'My Webhook',
    'url' => 'https://example.com/webhook',
    'events' => {
      'connection.created' => true,
      'connection.deleted' => true
    },
    'created_at' => '2024-01-15T10:30:00Z',
    'updated_at' => '2024-01-20T14:22:00Z',
    'last_triggered_at' => '2024-01-20T14:22:00Z'
  }
]
```

#### Create a Webhook

Register a new webhook endpoint.

```ruby theme={null}
webhook = client.webhooks.create(
  name: 'Connection Events Webhook',
  url: 'https://example.com/webhook',
  events: {
    'connection.created' => true,
    'connection.deleted' => true,
    'connection.updated' => true
  }
)
```

**Webhook Events:**

* `connection.created` - Triggered when a new connection is established
* `connection.deleted` - Triggered when a connection is removed
* `connection.updated` - Triggered when a connection is modified

**Request Body:**

* `name` (String): Friendly name for the webhook
* `url` (String): Your webhook endpoint URL
* `events` (Hash): Events to subscribe to

**Response:**

```ruby theme={null}
{
  'id' => 'webhook_123',
  'name' => 'Connection Events Webhook',
  'url' => 'https://example.com/webhook',
  'events' => {
    'connection.created' => true,
    'connection.deleted' => true,
    'connection.updated' => true
  },
  'created_at' => '2024-01-15T10:30:00Z',
  'updated_at' => '2024-01-15T10:30:00Z'
}
```

#### Retrieve a Webhook

Get details of a specific webhook.

```ruby theme={null}
webhook = client.webhooks.retrieve('webhook_123')
```

#### Update a Webhook

Modify an existing webhook.

```ruby theme={null}
updated = client.webhooks.update('webhook_123',
  name: 'Updated Webhook Name',
  url: 'https://example.com/new-webhook',
  events: {
    'connection.created' => true,
    'connection.deleted' => false
  }
)
```

#### Delete a Webhook

Remove a webhook subscription.

```ruby theme={null}
client.webhooks.delete('webhook_123')
```

#### Webhook Payload Example

When an event occurs, BundleUp sends a POST request to your webhook URL with the following payload:

```json theme={null}
{
  "id": "evt_1234567890",
  "type": "connection.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "conn_123abc",
    "external_id": "user_456",
    "integration_id": "int_slack",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

#### Webhook Security (Rails Example)

To verify webhook signatures in a Rails application:

```ruby theme={null}
# app/controllers/webhooks_controller.rb
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    signature = request.headers['BundleUp-Signature']
    payload = request.body.read

    unless verify_signature(payload, signature)
      render json: { error: 'Invalid signature' }, status: :unauthorized
      return
    end

    event = JSON.parse(payload)
    process_webhook_event(event)

    head :ok
  end

  private

  def verify_signature(payload, signature)
    secret = ENV['BUNDLEUP_WEBHOOK_SECRET']
    computed = OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
    ActiveSupport::SecurityUtils.secure_compare(computed, signature)
  end

  def process_webhook_event(event)
    case event['type']
    when 'connection.created'
      handle_connection_created(event['data'])
    when 'connection.deleted'
      handle_connection_deleted(event['data'])
    # ... more event handlers
    end
  end
end
```

### Auth API

Connect an end user's account and get back a `connection_id`. See [Authorization Flow](/docs/guides/auth/authorization-flow) for the full flow.

#### Build the Authorization URL

```ruby theme={null}
url = client.auth.build_authorization_url(
  client_id: 'your-client-id',
  integration_id: 'github',
  redirect_uri: 'https://app.example.com/callback',
  external_id: 'user_42', # optional
  state: 'random-csrf-token' # optional
)

# Redirect the user to `url`
```

The URL needs no API key, so you can also build it without a client:

```ruby theme={null}
url = BundleUp.build_authorization_url(
  client_id: 'your-client-id',
  integration_id: 'github',
  redirect_uri: 'https://app.example.com/callback'
)
```

**Parameters:**

* `client_id` (String, required): Your workspace client ID
* `integration_id` (String, required): The integration to connect
* `redirect_uri` (String, required): Must exactly match a redirect URI registered in your dashboard
* `external_id` (String, optional): Your own reference, stored on the connection
* `state` (String, optional): Returned unchanged on the redirect

#### Exchange the Code for a Connection

BundleUp redirects back to `redirect_uri` with a one-time `code`. Exchange it server-side:

```ruby theme={null}
connection = client.auth.get_connection_from_code(
  code: params[:code],
  redirect_uri: 'https://app.example.com/callback'
)

puts connection['connection_id']
```

**Parameters:**

* `code` (String, required): The `code` query parameter from the redirect
* `redirect_uri` (String, required): The same redirect URI used to build the authorization URL

**Response:**

```ruby theme={null}
{
  'connection_id' => 'conn_abc123',
  'external_id' => 'user_42',
  'integration_id' => 'github'
}
```

The code expires after 5 minutes and can only be exchanged once. An invalid, expired or reused code raises a `RuntimeError` that includes the API's error body. Missing arguments raise `ArgumentError`.

### Proxy API

Make direct HTTP requests to integration APIs through BundleUp.

#### Creating a Proxy Instance

```ruby theme={null}
proxy = client.proxy('conn_123abc')
```

#### GET Request

```ruby theme={null}
response = proxy.get('/api/users')
data = response.body
puts data
```

**With custom headers:**

```ruby theme={null}
response = proxy.get('/api/users', headers: {
  'X-Custom-Header' => 'value',
  'Accept' => 'application/json'
})
```

#### POST Request

```ruby theme={null}
response = proxy.post('/api/users', body: {
  name: 'John Doe',
  email: 'john@example.com',
  role: 'developer'
})

new_user = response.body
puts "Created user: #{new_user}"
```

**With custom headers:**

```ruby theme={null}
response = proxy.post(
  '/api/users',
  body: { name: 'John Doe' },
  headers: {
    'Content-Type' => 'application/json',
    'X-API-Version' => '2.0'
  }
)
```

#### PUT Request

```ruby theme={null}
response = proxy.put('/api/users/123', body: {
  name: 'Jane Doe',
  email: 'jane@example.com'
})

updated_user = response.body
```

#### PATCH Request

```ruby theme={null}
response = proxy.patch('/api/users/123', body: {
  email: 'newemail@example.com'
})

partially_updated = response.body
```

#### DELETE Request

```ruby theme={null}
response = proxy.delete('/api/users/123')

if response.success?
  puts 'User deleted successfully'
end
```

#### Working with Response Objects

The Proxy API returns Faraday response objects:

```ruby theme={null}
response = proxy.get('/api/users')

# Access response body
data = response.body

# Check status code
puts response.status # => 200

# Check if successful
puts response.success? # => true

# Access headers
puts response.headers['content-type']

# Handle errors
begin
  response = proxy.get('/api/invalid')
rescue Faraday::Error => e
  puts "Request failed: #{e.message}"
end
```

### Unified API

Access unified, normalized data across different integrations with a consistent interface.

#### Creating a Unified API Instance

```ruby theme={null}
unify = client.unify('conn_123abc')
```

#### Chat API

The Chat API provides a unified interface for chat platforms such as Slack and Discord. See [Chat](/docs/guides/unified/chat).

##### List Channels

Retrieve a list of channels from the connected chat platform.

```ruby theme={null}
result = unify.chat.channels(
  limit: 100,
  after: nil,
  include_raw: false
)

puts "Channels: #{result['data']}"
puts "Next cursor: #{result['metadata']['next']}"
```

**Parameters:**

* `limit` (Integer, optional): Maximum number of channels to return (default: 100, max: 1000)
* `after` (String, optional): Pagination cursor from previous response
* `include_raw` (Boolean, optional): Include raw API response from the integration (default: false)

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => 'C1234567890',
      'name' => 'general'
    },
    {
      'id' => 'C0987654321',
      'name' => 'engineering'
    }
  ],
  'metadata' => {
    'next' => 'cursor_abc123'  # Use this for pagination
  },
  '_raw' => {  # Only present if include_raw: true
    # Original response from the integration API
  }
}
```

**Pagination example:**

```ruby theme={null}
all_channels = []
cursor = nil

loop do
  result = unify.chat.channels(limit: 100, after: cursor)
  all_channels.concat(result['data'])
  cursor = result['metadata']['next']
  break if cursor.nil?
end

puts "Fetched #{all_channels.length} total channels"
```

#### Git API

The Git API provides a unified interface for version control platforms like GitHub, GitLab, and Bitbucket.

##### List Repositories

```ruby theme={null}
result = unify.git.repos(
  limit: 50,
  after: nil,
  include_raw: false
)

puts "Repositories: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => '123456',
      'name' => 'my-awesome-project',
      'full_name' => 'organization/my-awesome-project',
      'description' => 'An awesome project',
      'url' => 'https://github.com/organization/my-awesome-project',
      'created_at' => '2023-01-15T10:30:00Z',
      'updated_at' => '2024-01-20T14:22:00Z',
      'pushed_at' => '2024-01-20T14:22:00Z'
    }
  ],
  'metadata' => {
    'next' => 'cursor_xyz789'
  }
}
```

##### List Pull Requests

```ruby theme={null}
result = unify.git.pulls('organization/repo-name',
  limit: 20,
  after: nil,
  include_raw: false
)

puts "Pull Requests: #{result['data']}"
```

**Parameters:**

* `repo_name` (String, required): Repository name in the format 'owner/repo'
* `limit` (Integer, optional): Maximum number of PRs to return
* `after` (String, optional): Pagination cursor
* `include_raw` (Boolean, optional): Include raw API response

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => '12345',
      'number' => 42,
      'title' => 'Add new feature',
      'description' => 'This PR adds an awesome new feature',
      'draft' => false,
      'state' => 'open',
      'url' => 'https://github.com/org/repo/pull/42',
      'user' => 'john-doe',
      'created_at' => '2024-01-15T10:30:00Z',
      'updated_at' => '2024-01-20T14:22:00Z',
      'merged_at' => nil
    }
  ],
  'metadata' => {
    'next' => nil
  }
}
```

##### List Issues

```ruby theme={null}
result = unify.git.issues('organization/repo-name', limit: 20)

puts "Issues: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => 67890,
      'number' => 17,
      'title' => 'Timestamps drift on retry',
      'description' => 'Retried requests report the first attempt time',
      'state' => 'open',
      'url' => 'https://github.com/org/repo/issues/17',
      'user' => 'john-doe',
      'created_at' => '2024-01-15T10:30:00Z',
      'updated_at' => '2024-01-20T14:22:00Z',
      'closed_at' => nil
    }
  ],
  'metadata' => {
    'next' => nil
  }
}
```

##### List Tags

```ruby theme={null}
result = unify.git.tags('organization/repo-name', limit: 50)

puts "Tags: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'name' => 'v1.0.0',
      'commit_sha' => 'abc123def456'
    },
    {
      'name' => 'v0.9.0',
      'commit_sha' => 'def456ghi789'
    }
  ],
  'metadata' => {
    'next' => nil
  }
}
```

##### List Releases

```ruby theme={null}
result = unify.git.releases('organization/repo-name', limit: 10)

puts "Releases: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => '54321',
      'name' => 'Version 1.0.0',
      'tag_name' => 'v1.0.0',
      'description' => 'Initial release with all the features',
      'prerelease' => false,
      'url' => 'https://github.com/org/repo/releases/tag/v1.0.0',
      'created_at' => '2024-01-15T10:30:00Z',
      'released_at' => '2024-01-15T10:30:00Z'
    }
  ],
  'metadata' => {
    'next' => nil
  }
}
```

##### List Commits

```ruby theme={null}
result = unify.git.commits('organization/repo-name', branch: 'main', limit: 20)

puts "Commits: #{result['data']}"
```

`branch` is optional and accepts a branch name, tag or commit SHA. When it is omitted the
provider's default branch is used.

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'sha' => 'abc123def4567890abc123def4567890abc123de',
      'message' => 'Add commits endpoint',
      'url' => 'https://github.com/org/repo/commit/abc123def4567890abc123def4567890abc123de',
      'author' => 'Jane Doe',
      'author_email' => 'jane@example.com',
      'committed_at' => '2024-01-15T10:30:00Z'
    }
  ],
  'metadata' => {
    'next' => nil
  }
}
```

#### Tasks API

The Tasks API provides a unified interface for issue trackers and project management tools like Jira, Linear, Asana, Trello, ClickUp, monday.com, Basecamp, Wrike, and Todoist.

##### List Tasks

```ruby theme={null}
result = unify.tasks.tasks(
  limit: 100,
  after: nil,
  include_raw: false
)

puts "Tasks: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => 'PROJ-123',
      'url' => 'https://jira.example.com/browse/PROJ-123',
      'title' => 'Fix login bug',
      'status' => 'in_progress',
      'description' => 'Users are unable to log in',
      'created_at' => '2024-01-15T10:30:00Z',
      'updated_at' => '2024-01-20T14:22:00Z'
    }
  ],
  'metadata' => {
    'next' => 'cursor_def456'
  }
}
```

**Note:** Trello has no endpoint that lists every card, so it returns the cards the connected member is on. To list every card on a board instead, send the board id through the `params` passthrough parameter as `{"board": "5abbe4b7ddc1b351ef961414"}`. Trello also returns its collections in a single page, so `metadata['next']` is always `nil` for Trello connections.

**Filtering and sorting:**

```ruby theme={null}
open_tasks = result['data'].select { |task| task['status'] == 'open' }
sorted_by_date = result['data'].sort_by { |task| Time.parse(task['created_at']) }.reverse
```

##### List Projects

```ruby theme={null}
result = unify.tasks.projects(
  limit: 100,
  after: nil,
  include_raw: false
)

puts "Projects: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => '10001',
      'name' => 'Website Redesign',
      'status' => 'active',
      'url' => 'https://jira.example.com/browse/PROJ',
      'description' => 'All the work for the new marketing site',
      'created_at' => '2024-01-15T10:30:00Z',
      'updated_at' => '2024-01-20T14:22:00Z'
    }
  ],
  'metadata' => {
    'next' => 'cursor_def456'
  }
}
```

**Note:** Not every platform returns every field. Jira does not expose creation or update timestamps for projects, so `created_at` and `updated_at` are `nil` for Jira connections, and `status` is only set when Jira reports whether the project is archived.

#### Helpdesk API

The Helpdesk API provides a unified interface for customer support tools like Zendesk, ServiceNow, Zoho Desk, Gorgias, and Help Scout.

##### List Tickets

```ruby theme={null}
result = unify.helpdesk.tickets(
  limit: 100,
  after: nil,
  include_raw: false
)

puts "Tickets: #{result['data']}"
```

**Response:**

```ruby theme={null}
{
  'data' => [
    {
      'id' => '4182',
      'title' => 'Refund for order #1043',
      'description' => 'Hi, my order arrived damaged...',
      'status' => 'open',
      'priority' => 'high',
      'requester' => { 'id' => '381920', 'name' => 'Dana Ruiz', 'email' => 'dana@example.com' },
      'url' => 'https://acme.zendesk.com/agent/tickets/4182',
      'created_at' => '2024-01-15T10:30:00Z',
      'updated_at' => '2024-01-20T14:22:00Z'
    }
  ],
  'metadata' => {
    'next' => 'cursor_def456'
  }
}
```

##### Get a Ticket

Fetch one support ticket by ID. On ServiceNow the ID is the incident's `sys_id`.

```ruby theme={null}
result = unify.helpdesk.ticket('4182')

puts "Ticket: #{result['data']}"
```

A single resource carries no pagination, so there is no `metadata` on this response.

### MCP API

Reach a provider's own MCP server using a connection's credentials. BundleUp injects and refreshes the access token, so the connection ID is the only thing your agent needs to know about a user.

Supported for providers that run a first-party MCP server — see the [integrations page](https://www.bundleup.io/integrations). Others return an `mcp_not_supported` error.

BundleUp does not ship an MCP client. Hand `hosted` or `transport` to the one you already use, or send JSON-RPC yourself with `post` and `delete`, which return the response untouched as `Faraday::Response` objects, like the Proxy API.

#### Creating an MCP Instance

```ruby theme={null}
mcp = client.mcp('conn_123abc')
```

#### Model-Hosted MCP

OpenAI and Anthropic can connect to an MCP server themselves, with no tool mapping or dispatch loop on your side. Both accept only a single credential and no custom headers, so `hosted` returns the server URL alongside the API key and connection joined into one bearer.

```ruby theme={null}
hosted = client.mcp('conn_123abc').hosted

response = openai.responses.create(
  model: 'gpt-4o',
  input: 'What issues are assigned to me?',
  tools: [
    {
      type: 'mcp',
      server_label: 'linear',
      server_url: hosted[:url],
      authorization: hosted[:token],
      require_approval: 'never'
    }
  ]
)
```

Anthropic's connector takes the same pair as `url` and `authorization_token`.

`server_url` must be exactly the URL `hosted` returns — the proxy rebuilds the upstream URL from the provider's own base, so any path or query you append is ignored rather than rejected.

This sends your API key to the model provider, whose servers make the request. Use an MCP client in your own backend if that is not acceptable.

#### Using an MCP Client Library

`transport` returns the URL and headers if you would rather use an existing MCP client. Pass them to any client that supports the streamable HTTP transport.

```ruby theme={null}
transport = client.mcp('conn_123abc').transport

transport[:url]     # => "https://mcp.bundleup.io"
transport[:headers] # => { "Authorization" => "Bearer ...", "BU-Connection-Id" => "conn_123abc", ... }
```

#### Sending JSON-RPC Directly

MCP requires an `initialize` handshake before any other method. The session ID comes back on that first response and must be sent on every call after it.

```ruby theme={null}
mcp = client.mcp('conn_123abc')

# 1. Handshake
init = mcp.post({
  jsonrpc: '2.0',
  id: 1,
  method: 'initialize',
  params: {
    protocolVersion: '2025-06-18',
    capabilities: {},
    clientInfo: { name: 'my-agent', version: '1.0.0' }
  }
})

session_id = init.headers['mcp-session-id']
session = session_id ? { 'Mcp-Session-Id' => session_id } : {}

# 2. Confirm the handshake (a notification — no id, no response body)
mcp.post({ jsonrpc: '2.0', method: 'notifications/initialized' }, headers: session)

# 3. List tools
response = mcp.post({ jsonrpc: '2.0', id: 2, method: 'tools/list' }, headers: session)
result = parse(response)['result']

puts result['tools']
```

Providers may answer with `text/event-stream` rather than JSON, so responses need unwrapping either way:

```ruby theme={null}
require 'json'

def parse(response)
  return JSON.parse(response.body) unless response.headers['content-type'].to_s.include?('text/event-stream')

  data = response.body.lines
                 .select { |line| line.start_with?('data:') }
                 .map { |line| line[5..].strip }
                 .join("\n")

  JSON.parse(data)
end
```

Tool lists can be paginated. If `result['nextCursor']` is set, call `tools/list` again with `params: { cursor: result['nextCursor'] }` until it comes back empty.

Calling a tool follows the same shape:

```ruby theme={null}
response = mcp.post({
  jsonrpc: '2.0',
  id: 3,
  method: 'tools/call',
  params: { name: 'create_issue', arguments: { title: 'Login broken' } }
}, headers: session)
```

#### Sessions

MCP sessions live on the provider's server — BundleUp holds no session state. Close one when you are done:

```ruby theme={null}
mcp.delete(headers: { 'Mcp-Session-Id' => session_id })
```

#### Errors

BundleUp rejects a request before it reaches the provider by returning an HTTP error with a JSON body — the response is passed straight through, so check `response.success?` yourself.

```ruby theme={null}
response = mcp.post(body)

unless response.success?
  error = JSON.parse(response.body)
  # connection_invalid, connection_refresh_failed, mcp_not_supported, rate_limit
  warn "#{error['code']}: #{error['message']}"
end
```

Every JSON-RPC message counts toward the rate limit of 100 requests per 60 seconds, per connection — including the `initialize` handshake.

#### Several Connections

An agent often needs more than one provider for the same end user. With model-hosted MCP there is nothing to merge — pass one `mcp` tool per connection and the model provider keeps them apart by `server_label`:

```ruby theme={null}
connections = { 'slack' => user.slack_connection, 'linear' => user.linear_connection }

tools = connections.map do |label, connection_id|
  hosted = client.mcp(connection_id).hosted

  {
    type: 'mcp',
    server_label: label,
    server_url: hosted[:url],
    authorization: hosted[:token],
    require_approval: 'never'
  }
end
```

With an MCP client in your own backend, open one client per connection from its `transport`, prefix each tool name with a label (`slack__send_message`), and route calls back by that prefix. There is no merge helper in the SDK — how tools are namespaced, filtered and recovered from differs enough per agent that it is better written where you can see it.

**Filter before you hand tools to a model** — three providers is easily sixty tools, and accuracy drops as that list grows, so give the agent only the ones it needs.

## Error Handling

The SDK raises exceptions for errors. Always wrap SDK calls in rescue blocks for proper error handling.

```ruby theme={null}
begin
  connections = client.connections.list
rescue StandardError => e
  puts "Failed to fetch connections: #{e.message}"
end
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.