GitHub

Cosmo's GitHub integration connects to GitHub's official hosted MCP server (api.githubcopilot.com) — the same pattern as Slack and Atlassian. There is no binary to install. Each user authorizes with their own GitHub account, so the AI accesses only what that user can see.

How it works

Desktop
  └── RemoteOAuthProvider (staticClientId + staticClientSecret)
        └── StreamableHTTPClientTransport
              └── https://api.githubcopilot.com/mcp/   ← GitHub-hosted MCP server

Tokens are stored locally on each user's device (~/.cosmo/mcp-tokens/<instanceId>.json). They are never uploaded to the Cosmo server.

Unlike Atlassian (which supports Dynamic Client Registration), GitHub requires a registered OAuth App with a fixed Client ID and Client Secret — GitHub's authorization server (github.com/login/oauth) publishes no registration_endpoint. These are stored on the Cosmo server at seed time and passed to the OAuth flow as static credentials, the same as Slack.

Unlike Slack, GitHub has no workspace to bind first — every member connects independently with their own account. There is no admin-connects-first step.

What Cosmo can do

GitHub's hosted MCP server exposes a broad, evolving tool set covering repositories, issues, pull requests, and code search. Use tools/list in your MCP client to see the current full list — this integration does not curate or restrict it.

Prerequisites (self-hosted setup)

This is a one-time setup performed by whoever runs your Cosmo deployment — not something each org or member does.

1 — Register a GitHub OAuth App

1. Go to github.com/settings/developers → OAuth Apps → New OAuth App. (Use an organization's own settings instead if you want the app owned by the org rather than a personal account.)

2. Application name: e.g. Cosmo.

3. Homepage URL: your Cosmo web app URL.

4. Authorization callback URL:

   http://localhost:52625/oauth/callback

   This is a fixed local port the desktop app listens on — GitHub OAuth Apps require an exact match, so this must be entered precisely (no wildcard ports, unlike Slack).

5. Click Register application, then Generate a new client secret.

2 — Set server environment variables

COSMO_GITHUB_CLIENT_ID=your-oauth-app-client-id
COSMO_GITHUB_CLIENT_SECRET=your-oauth-app-client-secret

3 — Seed the provider

pnpm -C packages/server seed:providers

This registers GitHub in the ConnectorProvider table with authMode: REMOTE_OAUTH and mcpUrl: https://api.githubcopilot.com/mcp/. The seed is idempotent — safe to re-run. If the env vars above are unset, the seed skips GitHub entirely (logged as SKIP github: missing ...) rather than failing the whole run.

Connecting (per member)

Every member connects individually — there is no admin pre-binding step:

1. Open Cosmo Desktop → Integrations.
2. Find GitHub and click Connect.
3. Enter a label (e.g., Personal or Work).
4. A browser window opens to GitHub's OAuth screen. Sign in with your GitHub account and click Authorize.
5. Your personal tokens are stored locally — no teammate can read your repositories or issues.

Managing connections

cosmo mcp list
cosmo mcp remove <instance-id>

The CLI does not support connecting a new REMOTE_OAUTH instance — only the desktop app does. mcp list/mcp remove work against any connector regardless of how it was connected.

Credential storage

OAuth tokens are stored locally on the user's device:

~/.cosmo/mcp-tokens/<instanceId>.json

Each user's tokens are isolated to their own GitHub account.

Revoking access

• From Cosmo: click Disconnect next to GitHub in the Integrations screen, or run cosmo mcp remove <instance-id>. The local token file is deleted immediately.
• From GitHub: go to Settings → Applications → Authorized OAuth Apps, find Cosmo, and click Revoke. Existing tokens will fail on next use.

Troubleshooting

GitHub does not appear in the Integrations list at all. The deployment admin has not set COSMO_GITHUB_CLIENT_ID/COSMO_GITHUB_CLIENT_SECRET and re-run pnpm seed:providers. This is expected until that one-time setup is done — ask whoever runs your Cosmo instance.

"Incompatible auth server: does not support dynamic client registration." This means the OAuth App credentials above were never seeded — GitHub was seeded as NONE/unconfigured, or an older server build tried to connect without a registered app at all. Verify the env vars, re-run the seed, and reconnect.

"redirect_uri_mismatch" from GitHub. The callback URL registered on the OAuth App does not exactly match http://localhost:52625/oauth/callback. GitHub OAuth Apps require an exact match — check for a trailing slash or a different port.

Cosmo can see my personal repositories but not my organization's private ones. GitHub organizations block third-party OAuth Apps from their private repositories until an organization owner approves the app — the connection works, but the organization's repos (and the organization itself) are invisible to it, so Cosmo reports that it cannot find the repository you named. To approve it:

1. On GitHub, open Settings → Applications → Authorized OAuth Apps and select the Cosmo app.
2. Under Organization access, click Grant next to the organization (if you are an owner), or Request (an owner then approves it under the organization's Settings → Third-party access).
3. In Cosmo, Reconnect GitHub from Integrations so the connection picks up the new access.

If your organization does not restrict OAuth Apps, no approval is needed.

OAuth flow times out. The flow must complete within 2 minutes. If the browser window doesn't open, check that Cosmo is allowed to open external URLs in your OS settings.