Example

Build an MCP server for a GitHub-like API

Turn repository, issue, pull request, and workflow endpoints into agent tools with safe read defaults and reviewed write actions.

Jun 25, 202611 min readAdvanced

Steps

Separate read tools from write tools

Repository APIs usually mix safe reads with powerful mutations. Start by exposing repository lookup, issue search, pull request details, workflow status, and file reads. Keep create, merge, label, and dispatch actions private until reviewed.

Normalize common path parameters

Agents do better when owner, repo, issue_number, pull_number, and branch names are consistently described across operations.

Example

{
  "owner": "acme",
  "repo": "api",
  "pull_number": 42
}

Attach a least-privilege token

Use a token that can read only the repositories needed for the demo. Add write scopes only after the read path is tested and logs are redacted.

Test common agent tasks

Search docs for realistic phrases such as open release blockers, failing checks, recent merged PRs, or files changed in a pull request.

Example

curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"list failing workflow runs for a pull request"}}}'

Gate write actions

If you expose issue comments, labels, workflow dispatch, or merge operations, require explicit auth and consider a human approval step in the calling agent.

Production checks

Read routes work with repository-scoped credentials.

Write routes are private or require explicit workspace auth.

Issue and PR identifiers are validated before upstream calls.

Logs do not contain repository tokens, webhook secrets, or file contents beyond the response policy.

FAQ

Should an agent be able to merge pull requests through MCP?

Only with a reviewed policy, narrow credentials, and human approval where appropriate. Start with read-only PR inspection first.

What makes repository APIs hard for agents?

They have many similarly named endpoints and high-impact write actions. Good search_docs, route naming, and auth boundaries matter more than raw tool count.