Blog

How to give an AI agent access to GitHub

T. Krause ·

To give an AI agent access to GitHub, create a credential that covers only the repositories and permissions the agent needs. Store it on a server rather than in the agent's prompt or config file, and hand the agent GitHub operations as tools, for example through an MCP server. For your own account, a fine-grained personal access token is the quickest credential. For other people's accounts, register an OAuth app so each person signs in and grants access themselves.

This guide does both with Prompt TM, which stores the GitHub credential, exposes the GitHub API as typed tools and serves them at one MCP URL. The last section covers limiting the agent once it's connected. The agent never receives the token. It calls a tool such as GITHUB_CREATE_ISSUE, Prompt TM adds the credential to the request to GitHub, and the agent gets back the result.

Pick the credential

A fine-grained personal access token fits an agent that works on your own repositories. GitHub's token documentation recommends fine-grained tokens over classic ones. A fine-grained token belongs to one resource owner, can be limited to selected repositories, and carries individual permissions such as Issues or Contents. It has an expiry date, 30 days by default. Organization owners can require approval for these tokens, and until an owner approves, the token can only read public resources.

An OAuth app fits an agent that acts for your users. Each user signs in on GitHub and sees your app's name on the consent screen. OAuth apps ask for scopes instead of per-repository permissions, and GitHub's scope reference says the repo scope "grants full access to public and private repositories". Ask for the smallest set of scopes your tools need.

Prompt TM's own GitHub app (managed auth) lets users sign in without you registering anything. Its tokens reach only the repositories where the user installed the app, and they last eight hours with automatic refresh. Whether it's switched on shows as managed_auth_available in GET https://www.prompt-tm.com/api/v3/toolkits/github, and the auth config form greys out Prompt TM's app while it's off. Until then, use one of the two options below.

Option 1: your own account with a fine-grained token

1. Create the token on GitHub. Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Pick the resource owner and an expiry, choose Only select repositories and select the repositories the agent may use. Then grant only the permissions its tools need: Issues for filing and commenting on issues, Pull requests for opening and reviewing them, Contents for reading and writing files, Actions for workflow runs, and Webhooks (read and write) if you use GitHub triggers. GitHub always adds Metadata (read) to the token. Leave everything else at no access.

2. Add an auth config for GitHub. An auth config tells Prompt TM how a toolkit authenticates in your project. In the dashboard open Auth configs → New, choose GitHub and the Access token method. Or with the API:

curl -X POST https://www.prompt-tm.com/api/v3/auth_configs \
  -H "x-api-key: $PROMPT_TM_KEY" -H "content-type: application/json" \
  -d '{ "toolkit": { "slug": "github" }, "auth_config": { "auth_scheme": "BEARER_TOKEN" } }'

The response contains auth_config.id, which starts with ac_.

3. Connect the token. Pass it directly, with the user id the agent will act as:

curl -X POST https://www.prompt-tm.com/api/v3/connected_accounts \
  -H "x-api-key: $PROMPT_TM_KEY" -H "content-type: application/json" \
  -d '{ "auth_config": { "id": "ac_..." }, "user_id": "me",
        "connection": { "data": { "token": "github_pat_..." } } }'

Prompt TM checks the token with GitHub before it stores the token. A token GitHub rejects gets a 400, and the account is marked FAILED. A working one is ACTIVE, sealed with AES-256-GCM, and no API response ever includes it again. If you'd rather not paste the token into a terminal, POST /api/v3/connected_accounts/link returns a page on prompt-tm.com with a form for it.

4. Create an MCP server. In MCP servers → New, choose Custom, tick GitHub, and under Only some tools select the tools the agent should see. Copy the server URL.

5. Add it to your agent. For Claude Code:

claude mcp add --transport http github \
  "https://www.prompt-tm.com/mcp/mcp_...?user_id=me" \
  --header "x-api-key: $PROMPT_TM_KEY"

Scopes, shared configs and OAuth sign-in for that step are in Claude Code MCP server setup. Other clients are in the MCP client docs.

Option 2: your users' accounts with an OAuth app

1. Register an OAuth app on GitHub. Go to Settings → Developer settings → OAuth apps → New OAuth App (see GitHub's guide). Enter your app's name and homepage, and set the authorization callback URL to:

https://www.prompt-tm.com/api/v3/auth/callback

Create a client secret on the app's page and copy it with the client id.

2. Add an OAuth auth config. In Auth configs → New, choose GitHub, OAuth 2.0 and My own OAuth app, then paste the client id, the secret and the scopes. Prompt TM's default scopes for GitHub are repo, read:user, user:email, workflow, admin:repo_hook and notifications. Remove the ones your tools don't use. admin:repo_hook adds nothing while repo is in the list, because repo already covers repository webhooks. GitHub triggers need one of the two to register their webhook. The same config with the API:

curl -X POST https://www.prompt-tm.com/api/v3/auth_configs \
  -H "x-api-key: $PROMPT_TM_KEY" -H "content-type: application/json" \
  -d '{ "toolkit": { "slug": "github" },
        "auth_config": { "type": "use_custom_auth", "auth_scheme": "OAUTH2",
          "credentials": { "client_id": "...", "client_secret": "...", "scopes": ["repo", "read:user"] } } }'

3. Send each user a connect link. Use your own database id for the person as user_id:

curl -X POST https://www.prompt-tm.com/api/v3/connected_accounts/link \
  -H "x-api-key: $PROMPT_TM_KEY" -H "content-type: application/json" \
  -d '{ "auth_config_id": "ac_...", "user_id": "user_4821",
        "callback_url": "https://yourapp.example/settings/github" }'

The response holds a redirect_url. The user opens it and sees your project name, or the name set under Settings → Connect page branding. After the GitHub sign-in, they land back on your callback_url with status=success and a connected_account_id. Links expire after one hour.

4. Run the agent as that user. Put the same id in the MCP URL (?user_id=user_4821) or in the REST call. Each call uses that user's newest active GitHub account unless you pass connected_account_id. If GitHub ever refuses a token refresh, the account turns EXPIRED and your project webhook receives connected_account.expired, so you can send the user a new link.

Limit what the agent can do

A connected agent can do whatever the credential allows. Cut that down in four places.

The credential. A fine-grained token limits the agent to its repositories and permissions, and an OAuth app limits it to its scopes. GitHub enforces this part, whatever the agent asks for.

The tool list. A custom MCP server shows the agent only the tools you ticked. On the auth config, restrict_to_following_tools blocks every other tool for accounts connected through it, on every MCP server and in REST tool calls. It doesn't cover raw requests through POST /api/v3/tools/execute/proxy, which reach the GitHub API with whatever the credential allows. The catalogue marks tools that only read, such as GITHUB_LIST_ISSUES and GITHUB_GET_FILE_CONTENTS, and marks GITHUB_MERGE_PULL_REQUEST as destructive. The GitHub toolkit page lists every tool with its inputs.

Approvals. Set the MCP server's approvals to Ask a person before destructive calls or Ask a person before any call that changes something. A guarded call then returns approval_required: true and does nothing. The approval link goes to your webhook as approval.requested and to the server's page in the dashboard, never to the agent, so the agent can't approve its own merge. The router docs describe the flow.

The log. Every tool call is recorded under Logs with the tool, the user and the outcome, which tells you what the agent did after the fact.

What the agent can do once it's connected

The GitHub toolkit covers repositories, issues, pull requests, files, releases and Actions. An agent can search issues and code, file, update and comment on issues, and create a branch and write files to it. It can also open and review pull requests, dispatch a workflow and read its runs. GitHub triggers send issue, pull request, push, release and workflow run events to your project webhook, so an agent can start on a failed workflow run as soon as GitHub reports it.

The quickstart walks through option 1 from sign-up to the first call.