Feature Request: `get_agent_card` tool — load ALP-compatible agents directly from GitHub repos

[RodrigoMvs123]

Summary

Add a get_agent_card tool to the GitHub MCP Server that reads an
agent.alp.json file from any repository and returns it as a parsed,
schema-validated JSON object.

This closes the last gap between an agent living in a GitHub repo and that agent being live in any MCP-compatible runtime (Kiro, Claude Code, Claude Desktop, VS Code, Cursor) — in one tool call.

---

Background: what ALP is

Agent Load Protocol (ALP) is an open, MCP-compatible format for describing complete AI agents as a single portable artifact — the Agent Card (agent.alp.json).

What MCP is to tools, ALP is to entire agents.

An Agent Card declares:

• id, name, description — agent identity
• persona — the full system prompt
• tools[] — MCP-compatible tool endpoints (local or proxied HTTP)
• memory — session/persistent memory config
• llm — provider preference (any, user-resolved)
• server.url + server.transport — where the ALP Server lives
• toolsets, security.read_only, pagination — runtime control fields
• (mirrors concepts already in the GitHub MCP Server)

Current version: v0.9.0

Spec + reference implementation:
https://github.com/RodrigoMvs123/agent-load-protocol

Live demo MCP endpoint:
https://agent-load-protocol.onrender.com/mcp

Any MCP host can load the live demo agent today with:

{
  "mcpServers": {
    "hello-agent": {
      "type": "http",
      "url": "https://agent-load-protocol.onrender.com/mcp"
    }
  }
}

---

The gap this tool closes

The GitHub MCP Server already has get_file_contents, which can read any file from a repo — including agent.alp.json.

However, it returns a raw base64-encoded blob. The caller must:

1. Decode
2. JSON-parse
3. Validate manually

before the agent can be used.

get_agent_card would instead return a typed, schema-validated JSON object directly usable by any ALP-aware runtime.

This is the difference between GET /blob and GET /agent — structured semantics vs raw bytes.

---

Proposed tool

Tool name: get_agent_card
Toolset: repos (existing) — or a new lightweight alp toolset
Required OAuth scope: repo (same as get_file_contents)

Input parameters

Parameter	Type	Required	Description
owner	string	yes	Repository owner
repo	string	yes	Repository name
ref	string	no	Branch, tag, or commit SHA (defaults to repo default branch)
path	string	no	Path to the card file (defaults to agent.alp.json at repo root)

Output (parsed Agent Card object)

{
  "alp_version": "0.9.0",
  "id": "my-agent",
  "name": "My Agent",
  "persona": "You are a helpful assistant.",
  "tools": [
    {
      "name": "search",
      "description": "Search the knowledge base.",
      "endpoint": "https://my-server.com/api/search"
    }
  ],
  "server": {
    "url": "https://my-alp-server.com",
    "transport": "http"
  },
  "llm": { "provider": "any" },
  "memory": { "enabled": false }
}

If agent.alp.json is not found at the given path, the tool returns a clear error.
If the file exists but fails ALP schema validation, the tool returns a validation error identifying the offending fields.

---

How it unlocks the full GitHub → Kiro flow

With this tool approved and shipped, the end-to-end flow becomes:

Developer commits agent.alp.json to any GitHub repo
    ↓
Kiro (or any MCP host) calls get_agent_card { owner, repo }
    ↓
GitHub MCP Server fetches + parses + validates the card
    ↓
ALP runtime (Kiro) reads persona → injects into LLM context
ALP runtime reads tools[] → registers MCP-compatible endpoints
    ↓
Agent is live in the Kiro chat window

No local clone. No manual config. One tool call.

This is the scenario that ALP's remote card mode (v0.6.0) was designed for:

• Ship agent.alp.json in your GitHub repo
• Point a runtime at it
• Agent is live

The GitHub MCP Server is the natural discovery bridge — it already sits between GitHub and every major IDE.

get_agent_card completes that bridge.

---

Real-world implementation — hello-agent-alp-kiro (ALP v0.9.0)

Since this issue was opened, a real ALP v0.9.0 agent following this exact pattern has been built, deployed, and tested in Kiro.

Repository: https://github.com/RodrigoMvs123/hello-agent-alp-kiro
Live Agent Card: https://hello-agent-alp-kiro.onrender.com/agent
Live MCP endpoint: https://hello-agent-alp-kiro.onrender.com/mcp

All 4 tools (greet, echo, get_agent_card, chat) have been verified in Kiro.

How the flow works today (without get_agent_card)

Kiro currently uses get_file_contents to read the card:

get_file_contents({
  owner: "RodrigoMvs123",
  repo: "hello-agent-alp-kiro",
  path: "agent.alp.json"
})
→ returns base64 blob → manual decode → manual JSON parse → no schema validation

Then create_workflow_dispatch to trigger deployment:

create_workflow_dispatch({
  owner: "RodrigoMvs123",
  repo: "hello-agent-alp-kiro",
  workflow_id: "deploy.yml"
})
→ GitHub Actions injects secrets → agent deploys to Render → Kiro connects to /mcp

This works. But the get_file_contents step is the exact gap described in this issue.

What get_agent_card would replace

Exactly one step:

// today
get_file_contents({ owner, repo, path: "agent.alp.json" })
→ base64 blob, no validation, caller parses manually

// with get_agent_card
get_agent_card({ owner: "RodrigoMvs123", repo: "hello-agent-alp-kiro" })
→ typed, schema-validated Agent Card
→ runtime.deploy block surfaced directly — trigger, workflow path, credential refs
→ clear error if agent.alp.json is missing or malformed

The runtime.deploy block (new in ALP v0.9.0) is what makes this structured:

"runtime": {
  "deploy": {
    "trigger": "github_actions",
    "workflow": ".github/workflows/deploy.yml",
    "credentials": [
      { "ref": "GEMINI_API_KEY",    "source": "github_secrets" },
      { "ref": "RENDER_API_KEY",    "source": "github_secrets" },
      { "ref": "RENDER_SERVICE_ID", "source": "github_secrets" }
    ]
  }
}

When get_agent_card returns this as a typed object, Kiro knows immediately — without parsing a blob — that this agent deploys via GitHub Actions, what workflow to trigger, and what credentials are declared. The rest of the flow follows automatically.

The pattern works today with get_file_contents as a workaround. get_agent_card makes it first-class.

---

Alignment with existing GitHub MCP Server patterns

GitHub MCP Server feature	ALP equivalent
--toolsets flag / GITHUB_TOOLSETS env var	ALP toolsets.groups + toolsets.active
--read-only flag	ALP security.read_only + per-tool readonly: false
--dynamic-toolsets beta	ALP tools_discovery.mode: "dynamic"
server.json manifest at repo root	ALP server.alp.json manifest at server root
--insiders / insiders URL	ALP server.channel: "insiders" + insiders_url
Tool description env-var overrides	ALP description_override_key per tool
Deprecated tool aliases	ALP tools[].aliases + tools[].deprecated

ALP modeled several of these fields directly from the GitHub MCP Server architecture.

get_agent_card is a natural extension in the same direction.

---

Implementation sketch

// In pkg/github/repos.go (or a new alp.go file in the repos toolset)

func GetAgentCard(owner, repo, ref, path string) (*ALPCard, error) {
    // 1. Resolve path (default: "agent.alp.json")
    // 2. Call existing GetFileContents(owner, repo, path, ref)
    // 3. Decode base64 content
    // 4. json.Unmarshal into ALPCard struct
    // 5. Validate alp_version field is present and semver-parseable
    // 6. Return parsed struct (or validation error)
}

The implementation wraps get_file_contents — no new GitHub API calls needed.

ALP JSON schema:
https://github.com/RodrigoMvs123/agent-load-protocol/blob/main/schema/agent.alp.schema.json

---

Optional: server.alp.json companion endpoint

ALP v0.3.0+ defines a server.alp.json manifest that ALP-aware clients read before the full agent card to understand server capabilities:

• Supported transports
• Auth methods
• Available channels

A companion tool:

• get_alp_server_manifest
• or include_server_manifest (boolean flag on get_agent_card)

would surface this in one call.

This mirrors the GitHub MCP Server's own server.json at the repo root.

---

Considered alternative: use get_file_contents directly

Yes, get_file_contents already works. A client can:

1. Fetch file
2. Decode base64
3. Parse JSON manually

However, a dedicated tool is still valuable:

• Structured output — returns a typed object, not a blob
• Schema validation — catches malformed cards early
• Discoverability — get_agent_card is self-explanatory
• Default path resolution — encodes agent.alp.json convention
• Future-proofing — centralizes validation logic

---

Alignment with the MCP Server Cards specification (SEP-2127)

This proposal is directly relevant to the active MCP specification work on
SEP-2127: MCP Server Cards (modelcontextprotocol/modelcontextprotocol#2127),
which defines a standard for pre-connection server discovery via
.well-known/mcp/server-card.json.

Several open questions in SEP-2127 map precisely to patterns ALP already
implements in production:

SEP-2127 open question	ALP v0.9.0 answer
Should tools[] be included in the Server Card?	ALP tools[] with endpoint, input_schema, description — static, opt-in, runtime-agnostic
How should dynamic vs. static primitives be handled?	ALP proxy mode: card declares static tool shapes; ALP Server forwards calls to existing HTTP endpoints — zero LLM-side ambiguity
What is the relationship between Server Card and Agent Card?	ALP agent.alp.json is the Agent Card — identity + persona + tools + memory in one artifact, served at /agent
How does pre-connection discovery work without .well-known?	ALP server.alp.json at server root + AGENT_CARD_URL env var for remote loading from GitHub raw URLs
Who hosts the Server Card if the repo owner doesn't control .well-known?	ALP remote card mode (v0.6.0): card lives in the GitHub repo, a hosted ALP Server reads it — no .well-known control needed

The live ALP reference server at https://agent-load-protocol.onrender.com/mcp
already implements all of the above and is loadable today in any MCP-compatible
runtime. This makes get_agent_card not just a GitHub-specific convenience
tool, but a concrete early implementation of the discovery pattern SEP-2127 is
standardizing.

SEP-2127 was also linked to this issue by the specification maintainers,
confirming the connection between the two efforts.

---

References

• ALP repository: https://github.com/RodrigoMvs123/agent-load-protocol
• ALP live MCP endpoint: https://agent-load-protocol.onrender.com/mcp
• ALP JSON schema: https://github.com/RodrigoMvs123/agent-load-protocol/blob/main/schema/agent.alp.schema.json
• ALP SPEC.md: https://github.com/RodrigoMvs123/agent-load-protocol/blob/main/SPEC.md
• ALP pip library (v0.7.0): pip install alp-server
• hello-agent-alp-kiro repo: https://github.com/RodrigoMvs123/hello-agent-alp-kiro
• hello-agent live agent card: https://hello-agent-alp-kiro.onrender.com/agent
• hello-agent live MCP endpoint: https://hello-agent-alp-kiro.onrender.com/mcp