Example: GitHub MCP Server

Connect OpalServe to GitHub for repository access, issue management, pull requests, and code search. This works in both local and team mode.

Prerequisites

• A GitHub Personal Access Token or Fine-Grained Token
• OpalServe installed and initialized

Creating a GitHub Token

1. Go to github.com/settings/tokens
2. Click Generate new token > Fine-grained token (recommended)
3. Set the following permissions:

Permission	Access Level	Why
Contents	Read	Read files, list directories
Issues	Read & Write	Create/update issues
Pull Requests	Read & Write	Create/list PRs
Metadata	Read	Repository info, search

4. Select repository access: All repositories or specific ones
5. Click Generate token and copy the value

Token security

Never commit tokens to git. Use environment variables or let OpalServe store them in your local config (encrypted at rest in team-server mode).

Local Setup

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

Team Server Setup

On the team server, use an organization-level token so all team members benefit:

# Set the token as an environment variable on the server
export GITHUB_TOKEN=ghp_your_org_token

opalserve server add \
  --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=$GITHUB_TOKEN \
  --description "GitHub — org repositories" \
  --tags code,github

Team members get access after syncing:

opalserve sync
opalserve tools list --server github

Available Tools

Once connected, your AI tools have access to:

Tool	Description
search_repositories	Search GitHub repositories by keyword
get_file_contents	Read file contents from a repository
list_issues	List issues in a repository
create_issue	Create a new issue
update_issue	Update an existing issue
list_pull_requests	List pull requests
create_pull_request	Create a new pull request
list_commits	List commits on a branch
search_code	Search code across repositories
get_issue	Get details of a specific issue
add_issue_comment	Add a comment to an issue

Verification

# Check the server is connected
opalserve health --server github

# List all GitHub tools
opalserve tools list --server github

# Search for specific tools
opalserve tools search "issue"

HTTP API Usage

# Search for GitHub tools
curl "http://localhost:3456/api/v1/tools/search?q=issue&server=github" \
  -H "Authorization: Bearer $TOKEN"

# List issues via tool call
curl -X POST "http://localhost:3456/api/v1/tools/github%3Alist_issues/call" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner": "your-org", "repo": "your-repo"}'

# Create an issue
curl -X POST "http://localhost:3456/api/v1/tools/github%3Acreate_issue/call" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "your-org",
    "repo": "your-repo",
    "title": "Bug: login form broken",
    "body": "## Steps to Reproduce\n\n1. Go to /login\n2. Enter credentials\n3. Click submit\n\n## Expected\nRedirect to dashboard\n\n## Actual\n500 error"
  }'

Combining with Webhooks

In team mode, you can set up GitHub webhooks to automatically ingest context from your repositories. See the Integrations guide for setup instructions.

When webhooks are configured, OpalServe will:

• Index PR descriptions and comments
• Track issue activity
• Ingest changed file contents on push

This context becomes searchable via the knowledge base, so AI tools can answer questions like "what PRs were merged this week?" or "what's the status of the auth refactor?"

Multiple GitHub Accounts

If your team uses multiple GitHub accounts or organizations:

# Primary org
opalserve server add \
  --name github-main \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_main_org_token \
  --tags code,github

# Open source repos (different token)
opalserve server add \
  --name github-oss \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_oss_token \
  --tags code,github,oss

Both servers' tools are accessible and searchable through OpalServe's unified interface.