Connect a Service

Connect your AI to external services so your tools can make authenticated API calls. This guide walks through the full process using GitHub as the primary example, with notes on OAuth2, API keys, and other auth types.

The Scenario

You want your AI to create GitHub issues, list pull requests, and search code on your behalf. To do that, the AI needs authenticated access to the GitHub API.

Step 1: Check Available Templates

Kyew includes built-in templates for common providers. List them to see what's available:

connection(action="list", templates=true)

Templates pre-fill OAuth URLs, scopes, and base URLs so you don't have to look them up.

Step 2: Create the Connection

Option A: Bearer Token (simplest)

For GitHub personal access tokens, bearer auth is the fastest path:

connection(action="create",
  name="github",
  provider="github",
  auth_type="bearer",
  base_url="https://api.github.com")

Option B: API Key

Some services use API keys passed as query parameters or headers:

connection(action="create",
  name="openweather",
  provider="openweathermap",
  auth_type="api_key",
  api_key_config={
    header_name: "X-API-Key"
  },
  base_url="https://api.openweathermap.org")

Option C: OAuth2

For services that support OAuth2 (Google, Slack, etc.), use the OAuth flow:

connection(action="create",
  name="google_calendar",
  provider="google",
  auth_type="oauth2",
  oauth_config={
    auth_url: "https://accounts.google.com/o/oauth2/v2/auth",
    token_url: "https://oauth2.googleapis.com/token",
    client_id: "your-client-id",
    client_secret: "your-client-secret",
    scopes: ["https://www.googleapis.com/auth/calendar.readonly"]
  })

Step 3: Enter Credentials

For Bearer / API Key: Use the Secret URL

Generate a secure browser link so your token never appears in chat:

connection(action="secret_url", connection_id="conn_abc123")

This returns a one-time link like:

https://mcp.kyew.ai/secret/conn_abc123?token=eyJ...

Open it in your browser, paste your token or API key, and submit. The connection is now active.

For OAuth2: Authorize the Connection

Start the OAuth flow:

connection(action="authorize", connection_id="conn_def456")

This returns an authorization URL. Open it in your browser, sign in with the service, grant access, and the callback completes the connection automatically.

Step 4: Verify the Connection

Confirm the connection is working:

connection(action="get_token", connection_id="conn_abc123")

For OAuth2 connections, this also tests token refresh. If the token has expired, Kyew automatically refreshes it and returns a new one.

Step 5: Use the Connection in a Tool

Create a code tool that references the connection. Kyew injects the credentials as environment variables.

tool(action="create",
  name="github_list_prs",
  description="List open pull requests for a repository",
  tool_type="code",
  input_schema={
    type: "object",
    properties: {
      owner: { type: "string" },
      repo: { type: "string" }
    },
    required: ["owner", "repo"]
  },
  code_config={
    runtime: "javascript",
    allowed_domains: ["api.github.com"],
    connection_ids: ["conn_abc123"],
    code: "... see below ..."
  })

The handler reads the injected environment variable:

export default {
  async fetch(request) {
    const { owner, repo } = await request.json();

    // Kyew injects this from the connection named "github"
    const authHeader = process.env.KYEW_CONN_GITHUB_AUTH_HEADER;

    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/pulls?state=open`,
      {
        headers: {
          Authorization: authHeader,
          "User-Agent": "Kyew-Tool",
          Accept: "application/vnd.github.v3+json",
        },
      }
    );

    const prs = await res.json();

    return Response.json({
      count: prs.length,
      pull_requests: prs.map((pr) => ({
        number: pr.number,
        title: pr.title,
        author: pr.user.login,
        url: pr.html_url,
        created: pr.created_at,
      })),
    });
  },
};

Environment Variable Naming

Kyew generates environment variables from the connection name using this pattern:

The variable contains the full header value (e.g., Bearer ghp_xxxx or token xxxx), ready to pass as the Authorization header.

Managing Connections

List All Connections

connection(action="list")

Shows every connection with its status (active, pending, expired), provider, and auth type.

Update a Connection

Change headers, allowed tools, or other configuration:

connection(action="update",
  connection_id="conn_abc123",
  default_headers={
    Accept: "application/vnd.github.v3+json",
    "X-GitHub-Api-Version": "2022-11-28"
  })

Restrict to Specific Tools

Limit which tools can use a connection:

connection(action="update",
  connection_id="conn_abc123",
  allowed_tool_ids=["tool_pr_report", "tool_issue_creator"])

Delete a Connection

Remove a connection and revoke stored credentials:

connection(action="delete", connection_id="conn_abc123")

Next Steps

• Connections — Full connections documentation
• connection Reference — Complete parameter reference for all actions
• Build a Scheduled Report — Use a connection in an automated daily report