feat: add docs/agent.alp.json — ALP-compatible Agent Card for the GitHub MCP Server

[RodrigoMvs123]

[Feature Request]: Add docs/agent.alp.json — ALP Agent Card for the GitHub MCP Server

Summary

Hi — my name is Rodrigo (@RodrigoMvs123). I've been building ALP (Agent Load Protocol), a portable JSON-based format for describing complete AI agents. ALP uses MCP as its tool-call transport layer, and the GitHub MCP Server is one of the primary runtimes ALP targets.

• Repository: https://github.com/RodrigoMvs123/agent-load-protocol
• Live server: https://agent-load-protocol.onrender.com
• Schema: https://raw.githubusercontent.com/RodrigoMvs123/agent-load-protocol/main/schema/agent.alp.schema.json

---

What I am proposing

A single new file — no code changes:

docs/agent.alp.json

This file describes the GitHub MCP Server as an ALP-compatible Agent Card. It validates against the ALP schema at startup and makes the GitHub MCP Server discoverable and loadable by any ALP-compatible runtime — Claude Code, Kiro, Cursor — without any additional configuration.

{
  "$schema": "https://raw.githubusercontent.com/RodrigoMvs123/agent-load-protocol/main/schema/agent.alp.schema.json",
  "alp_version": "0.4.0",
  "id": "github-mcp-server",
  "name": "GitHub MCP Server",
  "description": "GitHub's official MCP Server — interact with repositories, issues, pull requests, actions, code security, and more via the GitHub API.",
  "agent_type": "single",
  "capabilities": [
    "tool-use",
    "github-integration",
    "streaming",
    "human-in-the-loop"
  ],
  "persona": "You are a GitHub assistant. You help developers interact with GitHub repositories, issues, pull requests, actions, code security, and workflows using the GitHub API.",
  "llm": { "provider": "any" },
  "tools_discovery": {
    "enabled": true,
    "mode": "dynamic"
  },
  "toolsets": {
    "groups": {
      "default": ["context", "issues", "pull_requests", "repos", "users"],
      "full": ["context", "issues", "pull_requests", "repos", "users", "actions", "code_security", "notifications", "orgs", "projects", "secret_protection", "copilot"],
      "readonly": ["repos", "issues", "pull_requests"]
    },
    "active": "default"
  },
  "security": {
    "read_only": false,
    "lockdown_mode": false,
    "max_tool_retries": 3
  },
  "server": {
    "url": "https://api.githubcopilot.com/mcp/",
    "transport": "http",
    "channel": "stable",
    "insiders_url": "https://api.githubcopilot.com/mcp/insiders",
    "modes": {
      "read_only": false,
      "lockdown": false
    }
  },
  "server_card": {
    "name": "io.github/github-mcp-server",
    "title": "GitHub MCP Server",
    "websiteUrl": "https://github.com/github/github-mcp-server",
    "repository": {
      "url": "https://github.com/github/github-mcp-server",
      "source": "github"
    },
    "remotes": [
      {
        "type": "streamable-http",
        "url": "https://api.githubcopilot.com/mcp/",
        "supportedProtocolVersions": ["2025-03-26"],
        "authentication": {
          "required": true,
          "schemes": ["bearer", "oauth2"]
        }
      }
    ]
  },
  "metadata": {
    "author": "GitHub",
    "version": "0.32.0",
    "tags": ["github", "mcp", "repos", "issues", "pull-requests", "actions", "copilot"],
    "repository": "https://github.com/github/github-mcp-server"
  }
}

Every field reflects the GitHub MCP Server's actual documented behavior — the default toolsets (context, issues, pull_requests, repos, users), the full toolset list, the insiders URL, dynamic toolset discovery, and the current release version (0.32.0).

---

How this file works

The $schema field points to the ALP schema hosted at:

https://raw.githubusercontent.com/RodrigoMvs123/agent-load-protocol/main/schema/agent.alp.schema.json

Any ALP-compatible runtime validates this file against that schema before loading the agent. If the file is invalid, the runtime refuses to load. This is the ALP compliance contract — not just a format, a validation guarantee.

---

ALP is now SEP-2127 compliant

Since the original issue was filed, ALP has shipped /.well-known/mcp-server-card — the discovery endpoint being standardised by the MCP Contributors #server-card-wg.

The live reference server responds at:

https://agent-load-protocol.onrender.com/.well-known/mcp-server-card

The proposed docs/agent.alp.json also includes a server_card block — a SEP-2127 compatible sub-object with name (reverse-DNS format), title, websiteUrl, repository, and remotes (transport + auth). This means the card is simultaneously:

• An ALP Agent Card — loadable by any ALP runtime
• A SEP-2127 MCP Server Card — discoverable by any client implementing the emerging standard

ALP's schema already includes the full server_card block as an optional field:

https://raw.githubusercontent.com/RodrigoMvs123/agent-load-protocol/main/schema/agent.alp.schema.json

---

Relevance to open issues and PRs in this repo

Several open issues and PRs here are solving problems that ALP already models at the agent description layer:

Issue / PR	Topic	ALP field
#2158	Configurable server name/title	name, id, description — required schema-validated fields
#2164 / #2192	Lockdown mode and read-only toolsets	security.read_only, security.lockdown_mode, per-tool readonly
PR #2294	Tool-level security policies	Per-tool auth.required_scopes and auth.accepted_scopes
PR #2208	Static CLI flags as upper bound for filtering	toolsets.active — named group acting as the active filter boundary

---

Why this matters for the broader MCP ecosystem

The MCP Contributors Discord #server-card-wg (led by @SamMorrowDrums and David Soria Parra from Anthropic) is actively working on SEP-2127 MCP Server Cards — a standardized discovery format for MCP servers at .well-known/mcp.json.

ALP's Agent Card is a working reference implementation of this concept, already live and validating against a published schema. The /.well-known/mcp-server-card endpoint is live now — closing the gap between ALP and SEP-2127 completely.

Adding docs/agent.alp.json to the GitHub MCP Server would make it the first major MCP server to ship an ALP-compatible card — a concrete step toward the portability the community is designing in the spec.

• Live agent endpoint: https://agent-load-protocol.onrender.com/agent
• Live .well-known endpoint: https://agent-load-protocol.onrender.com/.well-known/mcp-server-card
• Health check: https://agent-load-protocol.onrender.com/health

---

If there is interest I am happy to open a PR with this file.

@SamMorrowDrums — tagging you as you are active on both this repo and the MCP Contributors Discord #server-card-wg and #auth-wg-tool-scopes where ALP's per-tool OAuth scope declarations overlap directly with the work you are driving.