5 min read·Updated 2026-04-13

Connect GitHub via MCP

Create a skill that launches the GitHub MCP server, pass a token through the container environment, and verify the bot transitions into it on a real question.

What you will build

This recipe wires an agent to a GitHub account through an MCP server declared inside a skill. After setup, the agent can search repositories, read issues, and create pull requests in response to natural-language prompts.

The assumption behind this recipe is that you already understand the skill and MCP lifecycle concepts. If anything in the steps below looks surprising, go back to those pages — this recipe does not re-explain them.

Prerequisites

GolemCore Bot is running and reachable.
MCP is enabled in preferences/mcp.json ("enabled": true).
node and npx are available inside the runtime container. The default image includes them.
You have a GitHub personal access token with repo, issues, and pull_requests scopes (fine-grained tokens also work; see Variants below).

1. Create the skill

Write a new SKILL.md under workspace/skills/github-assistant/. The mcp.command launches the official GitHub MCP server via npx. The skill declares GITHUB_TOKEN in its vars: block and mcp.env passes it into the MCP process through a $${GITHUB_TOKEN} placeholder. At startup the runtime resolves that placeholder through the skill variable resolver — per-skill vars.json, then the workspace-wide variables.json, then the OS environment — and fails the handshake if nothing matches.

workspace/skills/github-assistant/SKILL.md

yaml

---
name: github-assistant
description: Work with GitHub repositories, issues, and pull requests via MCP
model_tier: coding
vars:
  GITHUB_TOKEN:
    description: Personal access token with repo, issues, and pull_requests scopes
    required: true
    secret: true
mcp:
  command: npx -y @modelcontextprotocol/server-github
  env:
    GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
  startup_timeout: 45
  idle_timeout: 10
---

You are a GitHub operations specialist.

Use the available MCP tools to work with repositories, issues, and
pull requests. When creating issues or PRs, summarize what you plan
to do first and wait for confirmation before calling a mutating tool.

Verify the file was saved

bash

docker exec golemcore-bot ls /app/workspace/skills/github-assistant/

Example output

text

SKILL.md

2. Pass the token

The skill references ${GITHUB_TOKEN}. The simplest way to satisfy it is to pass the token as a container environment variable at docker run time — the skill variable resolver falls through to the OS environment when no per-skill or workspace vars.json entry is set. See the Variants section for the per-skill file approach.

Restart the container with the token

bash

docker stop golemcore-bot && docker rm golemcore-bot

docker run -d \
  --name golemcore-bot \
  --shm-size=256m \
  --cap-add=SYS_ADMIN \
  -e STORAGE_PATH=/app/workspace \
  -e TOOLS_WORKSPACE=/app/sandbox \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -v golemcore-bot-data:/app/workspace \
  -v golemcore-bot-sandbox:/app/sandbox \
  -p 8080:8080 \
  ghcr.io/alexk-dev/golemcore-bot:latest

Verify the variable reached the container

bash

docker exec golemcore-bot printenv GITHUB_TOKEN | head -c 10

Example output

text

ghp_your_t

3. Trigger and verify

You do not toggle the skill by hand. Ask the bot for something that matches the skill's description and it calls skill_transition to switch itself in. On that first transition the runtime starts the MCP server, performs the handshake, and exposes each MCP tool as a native tool for the rest of the session.

Run /skills first to confirm the bot sees github-assistant in its installed list — /skills is a listing command only, not an activation command. Then open a chat and describe the task:

Example session

text

You:   List the three most recently opened issues in
       alexk-dev/golemcore-bot.

Agent: [transitions into github-assistant, calls list_issues]
       Found 3 open issues in alexk-dev/golemcore-bot:

       #142  Dashboard logs page freezes on large sessions
             opened 2 days ago by @alice

       #141  Model router falls back to balanced on unknown tier
             opened 3 days ago by @bob

       #140  MCP handshake timeout default should be 60s
             opened 5 days ago by @carol

If the reply uses tools from the GitHub MCP server, the handshake completed and the skill is sticky for the rest of the session.

First startup is slow

The first time the skill transitions in, npx downloads the MCP server package. That can take 15–30 seconds on a fresh container. If the handshake times out, raise mcp.startup_timeout on the skill — the example above uses 45 seconds.

Variants

The recipe above works on most setups but is not the only shape the skill can take. Adapt it to your constraints.

Fine-grained token

Generate a fine-grained personal access token scoped to one repository. Replace the classic token in GITHUB_TOKEN. Tighter blast radius if the token leaks.

Security

Local build of the MCP server

Run the MCP server from a local checkout instead of npx: command: node /app/workspace/mcp/server-github/dist/index.js. Useful for offline environments.

Offline

Read-only vs write skill

Split the skill into read-only and write variants. The read-only variant drops the repo scope; the write variant is only activated explicitly when you intend to change state.

Safety

Per-skill vars.json

Create workspace/skills/github-assistant/vars.json with {"GITHUB_TOKEN": "ghp_..."}. The skill variable resolver reads it before falling through to the OS environment, so each skill can hold its own token without touching docker run.

Multi-token

Gotchas

Handshake timeout on first run

Check: docker logs golemcore-bot | grep MCP. Fix: ensure npx is on PATH inside the container and startup_timeout is at least 30 seconds. First npx run downloads the package — slow networks need more time.

server won't start

GitHub 401 Unauthorized

Check: docker exec golemcore-bot printenv GITHUB_TOKEN. Fix: if empty, the container was started without -e GITHUB_TOKEN. Restart with the env var or switch to a per-skill variable.

auth errors

GitHub 403 on a specific operation

Check: token scopes on github.com. Fix: the token needs repo, issues, pull_requests for the full surface. Fine-grained tokens need matching repository-level permissions.

auth errors

Agent never touches the GitHub tools

Check: /skills shows github-assistant in the installed list. If not, the skill directory is missing or mis-named — reload it from Skills → Installed → Reload. If it is listed but the agent never transitions in, rephrase the request to match the skill description (e.g. mention 'GitHub repository' or 'pull request') so skill_transition fires.

tools missing

What to do next

Scheduled code review

Turn the skill into a recurring daily code review using Auto Mode and cron scheduling.

Cookbook

MCP Servers

Understand the full MCP lifecycle and state machine before writing more complex MCP skills.

Concept

User Guide

Skills

What a skill is, how to install one from the marketplace, and how to turn one on in a chat.

User Guide

MCP Servers

What an MCP server is, the two ways to declare one, and how the bot starts and stops it for you.

Cookbook

Scheduled Code Review

Set up a recurring daily code review using Auto Mode, a custom skill, and a cron schedule. Verify the first run and iterate.