Quickstart

Note that we are currently in the process of migrating from "BOSA Connector" to "GL Connectors"; some inconsistencies may appear during this time. For example:

1. The library name may still be bosa-connectors-binary, simply to ensure functionality while we need to do the big migration for the libraries and endpoints. We are currently in the process of migration. This GitBook will be updated as soon as the modifications are completed.

Please bear with us as we navigate these new changes.

This page assumes you already have credentials for GL Connectors. Please check Credentials on how to obtain both the API Key and how to create a user and/or initialize integrations.

To quickly get started with GL Connectors, you can use the shared credentials for authentication. Simply utilize the shared BOSA_API_URL, API_KEY, identifier, and user-secret to connect and authenticate your application. By using these credentials, you can seamlessly integrate and start leveraging the functionalities provided by Gl Connectors, allowing you to rapidly prototype and test your applications without the hassle of generating additional keys.

you can use https://api.bosa.id for BOSA_API_URL production or https://staging-api.bosa.id for BOSA_API_URL staging.

The following example uses list_pull_requests action to get 10 pull requests from GDP-ADMIN/bosa-sdk (note that the following code assumes the user already has a Github Integration). The example utilizes Bosa Connectors' Fluent style execution.

Note that you have to set up the integration first before using it. You can check the section after, or for more details, you can check the In-Depth Setup.

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url=BOSA_API_URL, api_key=API_KEY)
user = bosa.authenticate_bosa_user(identifier, secret)

# input parameters
params = {
    "limit": 10,
    "page": 1,
    "owner": "GDP-ADMIN",
    "repo": "bosa-sdk",
}
# execution
response = bosa.connect('github') \
    .action('list_pull_requests') \
    .params(params) \
    .max_attempts(3) \
    .token(user.token) \
    .run()

# Print the result
print(response.get_data())

Setting up an Integration

To set up a certain integration (e.g., github, google, gdrive, etc.), you need to request a connector authentication, which will create an OAuth2 login URL, which you can then follow to link an integration to your account. For more details, check the In-Depth Setup.

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url=BOSA_API_URL, api_key=API_KEY)
user = bosa.authenticate_bosa_user(identifier, secret)
has_integration = bosa.user_has_integration("github", user.token)

auth_url = bosa.initiate_connector_auth("github", user.token, "https://your-callback-uri.com")
print(f"Please visit {auth_url} to complete authentication.")

Setting up a Custom Integration

Unlike the previous section, this section highlights if you need to bring a custom configuration to modules that support it. For example, SQL Connection. The complete documentation can be found here in Custom Configurations.

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url="http://localhost:8000", api_key="your_api_key")
user = bosa.authenticate_bosa_user(identifier, secret)

config = {
    "url": "postgresql://postgres:postgres@localhost:5432/bosa",
    "identifier": "PSQLBosa"
}

integration_result = bosa.initiate_plugin_configuration("sql", user.token, config)
print("Integration initiated:", integration_result)

Multiple Integration

A BOSA user may add multiple integrations to a connector. When running the connector, you can choose an integration; otherwise the first integration added (the default) is used. The default integration can be changed or deleted.

Execute with Specific Integration

There are two ways to specify which integration to use when executing connector:

1. Parameter identifier: str on execute(...)

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url="http://localhost:8000", api_key="your_api_key")
user = bosa.authenticate_bosa_user(identifier, secret)

params = {
    "limit": 10,
    "page": 1,
    "owner": "GDP-ADMIN",
    "repo": "bosa-sdk",
    "token": user.token
}
execute_result = bosa.execute(
    "github", 
    "list_pull_requests", 
    identifier="my-github-account",
    **params,
)
print("Execute result:", execute_result)

1. Method identifier(identifier: str | None = None) on BOSA Connector Fluent.

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url=BOSA_API_URL, api_key=API_KEY)
user = bosa.authenticate_bosa_user(identifier, secret)

# input parameters
params = {
    "limit": 10,
    "page": 1,
    "owner": "GDP-ADMIN",
    "repo": "bosa-sdk",
}
# execution
response = bosa.connect('github') \
    .action('list_pull_requests') \
    .params(params) \
    .max_attempts(3) \
    .token(user.token) \
    .identifier('my-github-account')
    .run()

# Print the result
print(response.get_data())

Change Default Integration

The default integration can be changed. See the example code below.

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url="http://localhost:8000", api_key="your_api_key")
user = bosa.authenticate_bosa_user(identifier, secret)

select_result = bosa.select_integration("github", user.token, "my-github-account")
print("Integration selected:", select_result)

Delete Integration

An integration can be deleted. If the default integration is deleted, the most recently created integration becomes the new default. Example code for deleting an integration is shown below.

from bosa_connectors.connector import BosaConnector

bosa = BosaConnector(api_base_url="http://localhost:8000", api_key="your_api_key")
user = bosa.authenticate_bosa_user(identifier, secret)

delete_result = bosa.remove_integration("github", user.token, "my-github-account")
print("Integration deleted:", delete_result)

GL Connectors MCP

For more details on the capabilities and the URL for each MCP Servers, you can check the MCP guide for GL Connectors.

GL Connectors provide a comparable MCP server with the Connectors SDK functionality. We provide an MCP Server for each Connectors we have (they are hosted under different MCP endpoints). They are authorized using API Key and the preauthorized token that can be obtained through the above method using BOSA Connectors SDK. Here we give an example on how to connect to Connector's Github MCP Server.

Note that API Key and the Authorization Token is Connector's tokens; we assume that the user has created an integration using the Connectors first before using this. If the user has no integration, Connector will allow them to connect to the MCP Server, however, they will not be able to use any of its tools.

Please note that X-Bosa-Integration header is OPTIONAL. See more information here.

Claude Desktop (STDIO)

{
  "mcpServers": {
    "connector-github-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.bosa.id/github/mcp",
        "--header", "X-Api-Key:${API_KEY}",
        "--header", "Authorization:${TOKEN}",
        "--header", "X-Bosa-Integration:${INTEGRATION}"
      ],
      "env": {
        "API_KEY": "sk-client-...",
        "TOKEN": "Bearer eyJ...",
        "INTEGRATION": "user..."
      }
    }
  }
}

Connecting Directly (VSCode, Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "connectors-github-mcp": {
      "url": "https://api.bosa.id/github/mcp",
      "headers": {
        "X-Api-Key": "sk-client-...",
        "Authorization": "Bearer eyJ...",
        "X-Bosa-Integration": "user..."
      }
    }
  }
}