MCP Boundary by Impact Boundary Labs
Documentation navigation

MCP Tool Rules

GitHub MCP Tool Rules

This playbook shows rule examples for GitHub-like MCP servers.

Use a dedicated test repository first. A successful issue smoke test is not a claim that file writes, pushes, merges, repository creation, or broad GitHub support are safe.

For the general rule patterns, start with MCP Tool Rule Library.

Safe Starting Point

Start with one read/list issue tool in one test repository. Bind it to exact owner and repo values where the tool schema supports them.

Good first tools:

  • list issues in one test repo
  • read one issue by issue_number
  • list pull requests
  • read one pull request by pull_number
  • read file metadata without changing content

Keep file writes, pushes, merges, repository actions, workflow dispatch, and secret or permission tools hidden, blocked, or review-required.

Tool Surface Overview

Typical GitHub MCP surfaces include:

  • list issues
  • read issue details
  • comment on an issue
  • create an issue
  • read pull request metadata
  • update or create files
  • delete files
  • push files
  • merge pull requests
  • create or delete repositories
  • manage workflows, secrets, labels, or releases

Start with issue reads. Treat repository mutation and pull-request actions as high risk.

Write-Like Tools

Medium-risk actions:

  • create one clearly marked test issue
  • comment on one reviewed issue
  • apply a label to one reviewed issue
  • update a branch only in a dedicated test repository

Bind these to exact owner, repo, and issue or pull request numbers.

High-Risk Actions

Hide, block, or require review for:

  • create or update file
  • delete file
  • push files
  • force push
  • merge pull request
  • rebase
  • close or delete repository
  • create repository
  • workflow dispatch
  • secret or permission management
  • release publishing

These actions can change source, deploy code, or publish artifacts. Do not make them normal automatic agent tools in a first rule config.

Good Bindings

Strong GitHub bindings:

  • owner
  • repo
  • issue_number
  • pull_number
  • branch or ref
  • head_sha
  • file path
  • expected file sha
  • base branch
  • commit id

For issue comments, bind to the exact reviewed issue. For file writes, bind to repo, path, branch/ref, and the expected file or head sha. For merges, bind to the reviewed pull request and the exact head_sha.

Weak Bindings To Avoid

Avoid relying only on:

  • repository display text
  • issue title
  • pull request title
  • "current branch"
  • "latest PR"
  • file name without path and ref
  • agent memory of the selected repo

These are not stable permission boundaries.

Example Rule Configs

Allow Issue Listing In One Repository

Use this when the agent should inspect issues in a specific test repository.

The agent can see and call list_issues. MCP Boundary allows the call only with the configured top-level owner and repo values and limits the result size. This does not allow file writes, pushes, merges, or broad GitHub mutation.

json
{
"downstream_tool_name": "list_issues",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "allow",
"argument_rules": [
{
"field": "owner",
"required": true,
"allowed_values": ["example-org"]
},
{
"field": "repo",
"required": true,
"allowed_values": ["boundary-test-repo"]
}
],
"result_limits": {
"max_result_bytes": 32768
}
}

Require Review For Issue Comments

Use this when comments may be useful but should not run as normal automatic work.

The agent can see add_issue_comment, but MCP Boundary returns a review-required result unless a separate workflow handles it. The current release does not provide a dashboard approval queue.

json
{
"downstream_tool_name": "add_issue_comment",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "review_required",
"argument_rules": [
{
"field": "owner",
"required": true,
"allowed_values": ["example-org"]
},
{
"field": "repo",
"required": true,
"allowed_values": ["boundary-test-repo"]
},
{
"field": "issue_number",
"required": true,
"max_chars": 16
}
]
}

Keep File And PR Mutations Out Of The Normal Surface

Use these for file and pull-request mutation tools until you have stronger repo/path/ref/sha bindings and a tested workflow.

The agent cannot see create_or_update_file, and MCP Boundary blocks it before downstream execution through this path.

json
{
"downstream_tool_name": "create_or_update_file",
"exposure": "hidden",
"handling_mode": "generic_guarded",
"policy_input_mode": "block"
}

The dashboard can show merge_pull_request, but it is not normal allowed work.

json
{
"downstream_tool_name": "merge_pull_request",
"exposure": "dashboard_only",
"handling_mode": "generic_guarded",
"policy_input_mode": "review_required"
}

If you later test file updates, use a read-then-write pattern:

read file metadata -> record repo/path/ref/file sha -> update only same repo/path/ref with matching sha

For pull request merges:

read PR -> record pull_number and head_sha -> merge only if head_sha still matches

Do not retry merge or push after an uncertain result without re-reading the repository state.

Demo Walkthrough

Good GitHub walkthrough:

  • Use a dedicated test repo.
  • Expose only list_issues.
  • Prove one issue list call through Activity.
  • Keep file, repository, push, and merge tools hidden.
  • Call a hidden mutation tool and show tool_hidden with no downstream dispatch.
  • Optionally expose one issue comment as review_required.
  • Explain that branch/file/merge rules need stronger sha/ref binding before they become normal allowed work.

This makes the distinction clear: issue reads are a small proof, not a broad GitHub mutation claim.