> ## Documentation Index
> Fetch the complete documentation index at: https://docs-mcp.phake.app/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub OAuth

> Configure GitHub OAuth authentication for your MCP server.

Use the `github` strategy to authenticate users with their GitHub accounts. This is a preset of the generic OAuth flow with GitHub's endpoints pre-configured.

## Creating a GitHub OAuth App

1. Go to your GitHub account **Settings** > **Developer settings**
2. Select **OAuth Apps** > **New OAuth App**
3. Fill in the application details:
   * **Application name**: Choose a descriptive name (e.g., "My MCP Server")
   * **Homepage URL**: Your server's homepage URL (e.g., `https://my-mcp.example.com`)
   * **Authorization callback URL**:
     * For production: `https://your-domain.com/oauth/provider-callback`
     * For local development: `http://localhost:3000/oauth/provider-callback`
4. Click **Register application**
5. On the next page, click **Generate a new client secret**
6. Copy the **Client ID** and **Client Secret**

## Environment Setup

```bash theme={null}
AUTH_STRATEGY=github
OAUTH_CLIENT_ID=your-github-client-id
OAUTH_CLIENT_SECRET=your-github-client-secret
OAUTH_SCOPES=read:user,repo
OAUTH_REDIRECT_URI=https://your-server.com/oauth/provider-callback
```

## Preset Values

| Setting           | Default                                       |
| ----------------- | --------------------------------------------- |
| Accounts URL      | `https://github.com`                          |
| Authorization URL | `https://github.com/login/oauth/authorize`    |
| Token URL         | `https://github.com/login/oauth/access_token` |
| Default scopes    | `read:user`                                   |

## Available Scopes

GitHub OAuth scopes you may need:

| Scope         | Description                                     |
| ------------- | ----------------------------------------------- |
| `read:user`   | Read user profile information                   |
| `user:email`  | Read user email addresses                       |
| `read:org`    | Read organization membership                    |
| `repo`        | Full control of private and public repositories |
| `repo:status` | Commit status access                            |
| `workflow`    | Update GitHub Actions workflow files            |

## Example: GitHub API Access

```bash theme={null}
AUTH_STRATEGY=github
OAUTH_CLIENT_ID=Iv1.xxxxxxxx
OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OAUTH_SCOPES=read:user,repo
OAUTH_REDIRECT_URI=https://my-mcp.example.com/oauth/provider-callback
```

## Tool Context

When `AUTH_STRATEGY=github`, successful authentication populates the tool context with:

* `context.providerToken` — the GitHub access token
* `context.resolvedHeaders` — `{ Authorization: "Bearer <github-access-token>" }`
* `context.provider` — provider info object with `accessToken`, `refreshToken` (if granted), `expiresAt`, `scopes`
* `context.authStrategy` — `"github"`

## Example Tool

```typescript theme={null}
import { defineTool, assertProviderToken } from "@phake/mcp";
import { z } from "zod";

const listReposTool = defineTool({
  name: "list_repos",
  description: "List the authenticated user's repositories",
  inputSchema: z.object({
    sort: z.enum(["created", "updated", "pushed", "full_name"]).optional(),
    perPage: z.number().int().min(1).max(100).default(30),
  }),
  requiresAuth: true,
  handler: async (args, context) => {
    assertProviderToken(context);
    
    const url = new URL("https://api.github.com/user/repos");
    url.searchParams.set("sort", args.sort ?? "updated");
    url.searchParams.set("per_page", String(args.perPage));
    
    const response = await fetch(url.toString(), {
      headers: {
        ...context.resolvedHeaders,
        "Accept": "application/vnd.github.v3+json",
      },
    });
    return await response.json();
  },
});
```

## Self-Hosted GitHub Enterprise

If you're using GitHub Enterprise (self-hosted), override the preset endpoints:

```bash theme={null}
AUTH_STRATEGY=github
OAUTH_CLIENT_ID=your-enterprise-client-id
OAUTH_CLIENT_SECRET=your-enterprise-client-secret
OAUTH_SCOPES=read:user
OAUTH_REDIRECT_URI=https://my-mcp.example.com/oauth/provider-callback
OAUTH_AUTHORIZATION_URL=https://github.your-company.com/login/oauth/authorize
OAUTH_TOKEN_URL=https://github.your-company.com/login/oauth/access_token
```

## Getting User Info

Use `context.getUser()` to fetch the authenticated user's profile from GitHub:

```typescript theme={null}
const getProfileTool = defineTool({
  name: "get_profile",
  description: "Get the authenticated user's GitHub profile",
  inputSchema: z.object({}),
  requiresAuth: true,
  handler: async (_args, context) => {
    const { data: user, error } = await context.getUser();
    if (error) {
      return { error };
    }
    return user;
  },
});
```

Or use the standalone `getUser` helper with `USERINFO_ENDPOINTS`:

```typescript theme={null}
import { getUser, USERINFO_ENDPOINTS, assertProviderToken } from "@phake/mcp";

handler: async (_args, context) => {
  assertProviderToken(context);
  const user = await getUser(context.providerToken, USERINFO_ENDPOINTS.github);
  return user;
}
```