Integrations

OpalServe integrates with GitHub and Slack to bring external context into your team's AI tool workflow.

GitHub Integration

The GitHub integration enables two things:

1. MCP Server — GitHub MCP server gives AI tools access to repos, issues, PRs, and code search
2. Webhooks — Auto-ingest repository context when events happen (pushes, PR opens, issue creation)

Setting Up the GitHub MCP Server

Register the GitHub MCP server so your team's AI tools can interact with repositories:

opalserve server add \
  --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_your_org_token \
  --description "GitHub repositories and issues" \
  --tags code,github

Use an organization token

For team deployments, create a fine-grained personal access token or a GitHub App token scoped to your organization. Required permissions:

• Repository access: All repositories (or select specific ones)
• Permissions: Contents (read), Issues (read/write), Pull Requests (read/write), Metadata (read)

Setting Up GitHub Webhooks

Webhooks let OpalServe automatically ingest context from GitHub events. When a PR is opened or an issue is created, OpalServe can add the content to the knowledge base for AI tools to reference.

Step 1 — Configure the webhook endpoint

Make sure your OpalServe server is accessible from the internet (or from GitHub's webhook IPs). In your config:

{
  "integrations": {
    "github": {
      "webhookSecret": "your-webhook-secret",
      "autoContext": true,
      "events": ["push", "pull_request", "issues"]
    }
  }
}

Step 2 — Create the webhook in GitHub

1. Go to your repository or organization settings
2. Navigate to Webhooks > Add webhook
3. Set the payload URL to: https://your-opalserve-server:3456/api/v1/webhooks/github
4. Set Content type to application/json
5. Enter your webhook secret (same as webhookSecret in config)
6. Select events: Pushes, Pull requests, Issues
7. Click Add webhook

Step 3 — Verify

Push a commit or open a PR. Check the OpalServe logs:

  [info] GitHub webhook received: push to main (3 commits)
  [info] Auto-context: indexed 2 changed files from push

Auto-Context Ingestion

When autoContext is enabled, OpalServe processes these events:

Event	What gets indexed
Push	Changed file contents (for tracked branches)
Pull Request opened	PR title, description, and diff summary
Pull Request comment	Review comments and discussions
Issue opened	Issue title and body
Issue comment	Comment content

This context is added to the knowledge base and becomes searchable by AI tools. It enables questions like "what changed in the last PR?" or "what open issues do we have about authentication?"

Restricting Auto-Context

You can filter which repositories and branches trigger auto-context:

{
  "integrations": {
    "github": {
      "autoContext": true,
      "repos": ["my-org/frontend", "my-org/backend"],
      "branches": ["main", "develop"],
      "ignorePaths": ["*.lock", "node_modules/**", "dist/**"]
    }
  }
}

---

Slack Integration

The Slack integration enables:

1. MCP Server — Slack MCP server gives AI tools access to messages, channels, and workspace info
2. Slash Commands — Team members can search tools and knowledge base from Slack
3. Notifications — OpalServe sends alerts for server health issues

Setting Up the Slack MCP Server

opalserve server add \
  --name slack \
  --stdio "npx -y @modelcontextprotocol/server-slack" \
  --env SLACK_BOT_TOKEN=xoxb-your-bot-token \
  --description "Slack workspace" \
  --tags communication,slack

Creating a Slack App

To use slash commands and notifications, create a Slack app:

Step 1 — Create the app

1. Go to api.slack.com/apps
2. Click Create New App > From scratch
3. Name it "OpalServe" and select your workspace
4. Navigate to OAuth & Permissions

Step 2 — Configure bot token scopes

Add these scopes under Bot Token Scopes:

Scope	Purpose
chat:write	Send messages and notifications
commands	Register slash commands
channels:read	List channels
channels:history	Read channel messages (for MCP server)
users:read	Look up user info

Step 3 — Install to workspace

Click Install to Workspace and authorize. Copy the Bot User OAuth Token (xoxb-...).

Step 4 — Configure slash commands

Navigate to Slash Commands and create:

Command	Request URL	Description
/opalserve	https://your-server:3456/api/v1/slack/commands	Search tools and knowledge base
/opalserve-search	https://your-server:3456/api/v1/slack/commands	Search tools
/opalserve-context	https://your-server:3456/api/v1/slack/commands	Search knowledge base

Step 5 — Configure Event Subscriptions (optional)

If you want OpalServe to ingest Slack messages as context:

1. Navigate to Event Subscriptions
2. Enable events
3. Set the Request URL to https://your-server:3456/api/v1/slack/events
4. Subscribe to bot events: message.channels, message.groups

Step 6 — Update OpalServe config

{
  "integrations": {
    "slack": {
      "botToken": "xoxb-your-bot-token",
      "signingSecret": "your-signing-secret",
      "notificationChannel": "#engineering-ops",
      "slashCommands": true,
      "autoContext": false
    }
  }
}

Slash Commands

Team members can interact with OpalServe directly from Slack:

Search for tools:

/opalserve search create issue

Response:

Found 2 tools matching "create issue":
  github:create_issue — Create a new issue in a repository
  github:create_pull_request — Create a new pull request

Search the knowledge base:

/opalserve-context deployment process

Response:

Found 3 results for "deployment process":
  [0.92] Deployment Guide — "To deploy to production, merge to main..."
  [0.81] Release Checklist — "Before each release, ensure all staging..."
  [0.74] Incident Runbook — "If a deployment fails, roll back using..."

Check server status:

/opalserve status

Notifications

OpalServe can post notifications to a Slack channel for:

• Server disconnections — when an MCP server goes down
• Server reconnections — when a server comes back online
• Rate limit warnings — when a user is close to their limit
• Error spikes — when error rate exceeds a threshold

Configure the notification channel:

{
  "integrations": {
    "slack": {
      "notificationChannel": "#engineering-ops",
      "notifications": {
        "serverHealth": true,
        "rateLimitWarnings": true,
        "errorSpikes": true,
        "threshold": {
          "errorRate": 0.05,
          "rateLimitPercent": 0.8
        }
      }
    }
  }
}

Slack Auto-Context

When autoContext is enabled for Slack, OpalServe indexes messages from specified channels into the knowledge base. This can be useful for channels like #engineering-decisions or #architecture-discussions.

{
  "integrations": {
    "slack": {
      "autoContext": true,
      "autoContextChannels": ["#engineering-decisions", "#architecture"],
      "autoContextExcludeUsers": ["slackbot"]
    }
  }
}

Privacy

Auto-context ingestion indexes message content. Only enable this for channels where your team expects content to be used as AI context. Always communicate this to your team.

---

Integration Status

Check the status of all integrations:

opalserve status

  Integrations:
    GitHub   webhooks active (12 events/24h, auto-context: on)
    Slack    connected (slash commands: on, notifications: #engineering-ops)

Or via the admin dashboard, navigate to the Integrations section to see webhook delivery history, event counts, and configuration.