Add external OAuth token script support for managed environments

[Copilot]

Environments like Coder workspaces manage OAuth credentials externally and provide CLI commands to retrieve fresh tokens. Previously, users had to manually prepopulate ~/.gitlab-mcp-token.json, which would expire and break the MCP server.

Changes

Core Implementation (oauth.ts)

• Added GITLAB_OAUTH_TOKEN_SCRIPT environment variable to execute external commands for token retrieval
• Implemented executeTokenScript() with argument parsing supporting both single and double quotes
• Modified getAccessToken() to prioritize token script over standard OAuth flow
• Made GITLAB_OAUTH_CLIENT_ID optional when using token script

Configuration

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_TOKEN_SCRIPT": "coder external-auth access-token gitlab",
        "GITLAB_API_URL": "https://gitlab.example.com/api/v4"
      }
    }
  }
}

Script Requirements

• Output token to stdout (whitespace trimmed automatically)
• Complete within 30 seconds
• Exit successfully (code 0)

Documentation

• Updated README.md with usage examples for Coder workspaces
• Added "External Token Script (Advanced)" section to docs/oauth-setup.md
• Included troubleshooting guide for common failure scenarios

Testing

• Added test suite covering argument parsing, error handling, and edge cases
• Verified backward compatibility with existing OAuth flow

Original prompt

---

This section details on the original issue you should resolve

<issue_title>OAuth Token Refresh Script</issue_title>
<issue_description>Hello,

Do you think it would be possible to add another configuration option that allows delegation of OAuth token retrieval to an external script? I am using the MCP server in a Coder workspace (https://coder.com) which has its own mechanism for maintaining OAuth credentials for our GitLab instance. I can retrieve the access token with a command like:

coder external-auth access-token gitlab

Right now, I prepopulate ~/.gitlab-mcp-token.json, with this value which works great with the MCP server until the token expires. If I could set an env var like GITLAB_OAUTH_TOKEN_SCRIPT, and the mcp server could delegate token retrieval to that script, I think it would be a nice quality of life improvement.

I'm open to submitting a PR if you are open to the feature.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes OAuth Token Refresh Script #312

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.