5 min read·Updated 2026-04-10

Connect GitHub via MCP

Create a skill that launches the GitHub MCP server, pass a token through the container environment, activate, and verify with a test query.

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 mcp.env passes the token through a skill variable placeholder.

workspace/skills/github-assistant/SKILL.md

yaml

---
name: github-assistant
description: Work with GitHub repositories via MCP
tier: coding
mcp:
  command: npx -y @modelcontextprotocol/server-github
  env:
    GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
  startup_timeout: 30
  idle_timeout: 10
---

Use the available MCP tools to work with GitHub.
Focus on the repositories the user asks about.
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 runtime resolves that against skill variables first, then the OS environment inside the container. The simplest path is to pass the token as a container environment variable at docker run time.

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. Activate and verify

Go to Chat and activate the skill. The runtime starts the MCP server on first activation, performs the handshake, and exposes each MCP tool as a native tool for the rest of the session.

Chat command

text

/skills activate github-assistant

Then ask a read-only question that exercises the MCP tools:

Example session

text

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

Agent: [calls github.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 agent lists tools that start with github. (or mcp__github__ depending on the naming convention), the handshake completed and the MCP server is registered.

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 variables

Set GITHUB_TOKEN as a skill variable instead of container env: variables: { GITHUB_TOKEN: ghp_... } in SKILL.md. Useful when multiple skills need different tokens.

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 says no GitHub tools available

Check: /skills list — is github-assistant active? Fix: if not, run /skills activate github-assistant. Tools only register while the skill is active.

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 sticky activation works, and the SKILL.md contract. For concrete recipes, see the Cookbook.

User Guide

MCP Servers

How MCP servers are declared in skills, how the runtime manages their lifecycle, and how to debug handshake failures.

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.