Skip to content

Commit 3ff1925

Browse files
dinpddinpd
committed
Add AgentID authorization contract example
1 parent b5397f6 commit 3ff1925

2 files changed

Lines changed: 247 additions & 0 deletions

File tree

‎docs/agentid-provider-contract.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# AgentID Provider Authorization Contract Example
2+
3+
The GitHub MCP Server already supports several access controls, including
4+
toolsets, individual tool allowlists, excluded tools, read-only mode, lockdown
5+
mode, OAuth/PAT scope filtering, and GitHub's native API authorization model.
6+
7+
For organizations routing GitHub MCP Server traffic through an enterprise MCP
8+
gateway, an additional pattern is to publish a provider-side authorization
9+
contract that describes the blast radius and context requirements for each
10+
tool. A gateway can import that contract, apply local agent/user/job policy,
11+
and then forward high-risk tool calls with a scoped authorization receipt.
12+
13+
This does not replace GitHub API authorization. It gives the enterprise gateway
14+
a machine-readable contract for deciding whether an agent-originated tool call
15+
should be attempted before the GitHub MCP Server and GitHub API enforce their
16+
normal permissions.
17+
18+
## Example Flow
19+
20+
```text
21+
Agent or IDE
22+
-> Enterprise MCP gateway
23+
-> AgentID authorization check
24+
-> GitHub MCP Server
25+
-> GitHub API authorization
26+
-> Tool execution
27+
```
28+
29+
For provider-hosted or enterprise-routed deployments, high-risk tools such as
30+
creating pull requests, merging pull requests, updating repository contents, or
31+
deleting files can require:
32+
33+
- a declared job or task boundary
34+
- a target repository/resource binding
35+
- a user or agent identity binding
36+
- approval or just-in-time authority
37+
- a short-lived authorization receipt
38+
- an audit event that can be correlated with the eventual GitHub API action
39+
40+
## Example Contract
41+
42+
The following example uses the AgentID provider MCP authorization contract shape.
43+
It is illustrative and intentionally scoped to a small set of repository and
44+
pull request tools.
45+
46+
```yaml
47+
$schema: https://raw.githubusercontent.com/dinpd/AgentID/main/schema/provider-mcp-contract.schema.json
48+
49+
provider_agentid:
50+
provider: github
51+
mcp_server: github-mcp-server
52+
version: example
53+
tools:
54+
get_file_contents:
55+
action: read
56+
risk: low
57+
resource_template: github/repo/{owner}/{repo}/contents/{path}
58+
data_from: github_repository
59+
data_to: agent_context
60+
requires_jit: false
61+
receipt_required: false
62+
input_schema:
63+
type: object
64+
required:
65+
- owner
66+
- repo
67+
- path
68+
properties:
69+
owner:
70+
type: string
71+
repo:
72+
type: string
73+
path:
74+
type: string
75+
76+
create_pull_request:
77+
action: write
78+
risk: high
79+
resource_template: github/repo/{owner}/{repo}/pulls
80+
data_from: agent_context
81+
data_to: github_repository
82+
requires_jit: true
83+
approval: human_confirm
84+
receipt_required: true
85+
authorization_requirements:
86+
required_context:
87+
- tenant_id
88+
- agent_id
89+
- user_id
90+
- job_id
91+
- owner
92+
- repo
93+
- approval_id
94+
bind_receipt_to:
95+
- tenant_id
96+
- agent_id
97+
- user_id
98+
- tool
99+
- action
100+
- resource
101+
- job_id
102+
- owner
103+
- repo
104+
- approval_id
105+
- jit_grant_id
106+
resource_template: github/repo/{owner}/{repo}/pulls
107+
receipt_ttl_seconds: 300
108+
single_use: true
109+
110+
merge_pull_request:
111+
action: write
112+
risk: high
113+
resource_template: github/repo/{owner}/{repo}/pull/{pull_number}/merge
114+
data_from: agent_context
115+
data_to: github_repository
116+
requires_jit: true
117+
approval: human_confirm
118+
receipt_required: true
119+
authorization_requirements:
120+
required_context:
121+
- tenant_id
122+
- agent_id
123+
- user_id
124+
- job_id
125+
- owner
126+
- repo
127+
- pull_number
128+
- approval_id
129+
bind_receipt_to:
130+
- tenant_id
131+
- agent_id
132+
- user_id
133+
- tool
134+
- action
135+
- resource
136+
- job_id
137+
- owner
138+
- repo
139+
- pull_number
140+
- approval_id
141+
- jit_grant_id
142+
resource_template: github/repo/{owner}/{repo}/pull/{pull_number}/merge
143+
receipt_ttl_seconds: 180
144+
single_use: true
145+
146+
create_or_update_file:
147+
action: write
148+
risk: high
149+
resource_template: github/repo/{owner}/{repo}/contents/{path}
150+
data_from: agent_context
151+
data_to: github_repository
152+
requires_jit: true
153+
approval: human_confirm
154+
receipt_required: true
155+
authorization_requirements:
156+
required_context:
157+
- tenant_id
158+
- agent_id
159+
- user_id
160+
- job_id
161+
- owner
162+
- repo
163+
- path
164+
- approval_id
165+
bind_receipt_to:
166+
- tenant_id
167+
- agent_id
168+
- user_id
169+
- tool
170+
- action
171+
- resource
172+
- job_id
173+
- owner
174+
- repo
175+
- path
176+
- approval_id
177+
- jit_grant_id
178+
resource_template: github/repo/{owner}/{repo}/contents/{path}
179+
receipt_ttl_seconds: 300
180+
single_use: true
181+
182+
delete_file:
183+
action: write
184+
risk: critical
185+
resource_template: github/repo/{owner}/{repo}/contents/{path}
186+
data_from: agent_context
187+
data_to: github_repository
188+
requires_jit: true
189+
approval: human_confirm
190+
receipt_required: true
191+
authorization_requirements:
192+
required_context:
193+
- tenant_id
194+
- agent_id
195+
- user_id
196+
- job_id
197+
- owner
198+
- repo
199+
- path
200+
- approval_id
201+
bind_receipt_to:
202+
- tenant_id
203+
- agent_id
204+
- user_id
205+
- tool
206+
- action
207+
- resource
208+
- job_id
209+
- owner
210+
- repo
211+
- path
212+
- approval_id
213+
- jit_grant_id
214+
resource_template: github/repo/{owner}/{repo}/contents/{path}
215+
receipt_ttl_seconds: 180
216+
single_use: true
217+
```
218+
219+
## How an Enterprise Gateway Can Use This
220+
221+
An enterprise gateway can use the contract to:
222+
223+
1. Import the allowed GitHub MCP tools into a local policy manifest.
224+
2. Bind agent authorization to a job, owner, repository, pull request, or file path.
225+
3. Require approval or just-in-time authority for write/destructive tools.
226+
4. Attach a scoped receipt to forwarded high-risk tool calls.
227+
5. Correlate gateway authorization decisions with GitHub audit/API events.
228+
229+
This is complementary to this server's built-in configuration and GitHub's API
230+
authorization model:
231+
232+
- Toolsets and read-only mode decide which tools are exposed.
233+
- PAT, OAuth, and GitHub App permissions decide what the token can do.
234+
- GitHub API authorization remains the final enforcement point for the actual
235+
operation.
236+
- The provider authorization contract helps an enterprise gateway decide
237+
whether a specific agent-originated action should be attempted at all.
238+
239+
For a reference implementation of this contract shape, see the AgentID project:
240+
<https://github.com/dinpd/AgentID>.

‎docs/policies-and-governance.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,13 @@ The GitHub MCP Server provides access to GitHub resources and capabilities throu
4949

5050
For integration architecture and implementation details, see the [Host Integration Guide](https://github.com/github/github-mcp-server/blob/main/docs/host-integration.md).
5151

52+
Organizations that route GitHub MCP Server traffic through an enterprise MCP
53+
gateway can also use a provider authorization contract to describe per-tool
54+
blast radius, required context, approval requirements, and receipt bindings.
55+
See the [AgentID provider authorization contract example](./agentid-provider-contract.md)
56+
for an optional pattern that complements toolsets, read-only mode, token scopes,
57+
and GitHub's native API authorization model.
58+
5259
## Where It's Used
5360

5461
The GitHub MCP server can be accessed in various environments (referred to as "host" applications):

0 commit comments

Comments
 (0)