📝 (docs): Add a user guide for connecting AI clients over MCP
Changes
3 files changed, +95 -2
MODIFY
README.md
+3 -2
@@ -125,13 +125,14 @@
125
125
126
126
An MCP (Model Context Protocol) server is exposed via the Quarkiverse extension
127
127
`io.quarkiverse.mcp:quarkus-mcp-server-http` (1.13.1), mirroring the REST API's feature set as
128
-MCP tools.
128
+MCP tools. Client setup (Claude Code, Claude Desktop, others) is described in
129
+[docs/users/mcp.md](docs/users/mcp.md).
129
130
130
131
- **Transport:** Streamable HTTP at `/mcp` (the extension also serves the legacy HTTP/SSE
131
132
variant, but Streamable HTTP is the one git-shark uses)
132
133
- **Auth:** same personal access tokens as the REST API, sent as `Authorization: Bearer <token>`
133
134
on the MCP request; read tools work anonymously for public repos, write tools require a token
134
- and repository ownership (commenting only requires read access)
135
+ and owner or collaborator rights (commenting only requires read access)
135
136
136
137
| Area | Tools |
137
138
|---|---|
MODIFY
docs/README.md
+3 -0
@@ -24,6 +24,9 @@
24
24
- **[Organisations](users/organisations.md)** — shared repository namespaces
25
25
with guest/member/owner roles: creating an org, managing members, org
26
26
repositories.
27
+- **[AI clients (MCP)](users/mcp.md)** — connect Claude Code, Claude Desktop, or
28
+ any MCP client to your instance: token setup, client configuration, available
29
+ tools.
27
30
28
31
### For admins
29
32
ADD
docs/users/mcp.md
+89 -0
@@ -0,0 +1,89 @@
1
+# Using git-shark from an AI client (MCP)
2
+
3
+git-shark exposes an [MCP](https://modelcontextprotocol.io) (Model Context Protocol)
4
+server, so AI clients such as Claude Code, Claude Desktop/claude.ai, or any other
5
+MCP-capable tool can browse and manage your repositories, issues, and merge requests
6
+by talking to your instance directly.
7
+
8
+- **URL:** `https://<your-instance>/mcp`
9
+- **Transport:** Streamable HTTP (use this one; the legacy HTTP/SSE variant also
10
+ exists but Streamable HTTP is the supported transport)
11
+- **Auth:** your personal access token as `Authorization: Bearer <token>`
12
+
13
+The MCP tools enforce exactly the same rules as the web UI and REST API: reading
14
+public repositories works without a token, everything else acts as the user the
15
+token belongs to.
16
+
17
+## 1. Create a personal access token
18
+
19
+1. Log in and open **Account → Access tokens** (`/settings/tokens`).
20
+2. Give the token a label (e.g. `claude`) and create it.
21
+3. Copy the token now — it is shown only once. This is the same kind of token used
22
+ for the REST API and for `git push` over HTTP.
23
+
24
+Revoke it any time on the same page.
25
+
26
+## 2. Connect a client
27
+
28
+### Claude Code
29
+
30
+```bash
31
+claude mcp add --transport http gitshark https://<your-instance>/mcp \
32
+ --header "Authorization: Bearer <your-token>"
33
+```
34
+
35
+Then verify with `/mcp` inside Claude Code — the `gitshark` server and its tools
36
+should be listed. Without the header everything still connects, but only public
37
+reads work.
38
+
39
+### Claude Desktop / claude.ai
40
+
41
+Custom connectors in Claude Desktop and claude.ai don't support custom headers
42
+directly. Bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) in
43
+`claude_desktop_config.json`:
44
+
45
+```json
46
+{
47
+ "mcpServers": {
48
+ "gitshark": {
49
+ "command": "npx",
50
+ "args": [
51
+ "mcp-remote",
52
+ "https://<your-instance>/mcp",
53
+ "--header",
54
+ "Authorization: Bearer <your-token>"
55
+ ]
56
+ }
57
+ }
58
+}
59
+```
60
+
61
+### Other MCP clients
62
+
63
+Any client that supports Streamable HTTP servers with a custom header works the
64
+same way: endpoint `https://<your-instance>/mcp`, header
65
+`Authorization: Bearer <your-token>`.
66
+
67
+## What the tools can do
68
+
69
+| Area | Tools | Token needed? |
70
+|---|---|---|
71
+| Repositories | `listRepositories`, `getRepository` | no (public repos) |
72
+| | `createRepository`, `deleteRepository` | yes (owner) |
73
+| Issues | `listIssues`, `getIssue` | no (public repos) |
74
+| | `createIssue`, `updateIssueStatus`, `deleteIssue` | yes (owner or collaborator) |
75
+| Merge requests | `listMergeRequests`, `getMergeRequest`, `listMergeRequestComments` | no (public repos) |
76
+| | `createMergeRequest`, `mergeMergeRequest`, `closeMergeRequest` | yes (owner or collaborator) |
77
+| | `addMergeRequestComment` | yes (any reader of the repository) |
78
+| You | `currentUser` | yes |
79
+
80
+Private repositories are visible to their owner and collaborators only — with a
81
+token, reads cover your own private repositories too.
82
+
83
+## Troubleshooting
84
+
85
+| Symptom | Cause / fix |
86
+|---|---|
87
+| Tool call fails with `A valid personal access token is required` | The client didn't send the `Authorization: Bearer` header, or the token was revoked. Re-check the header configuration and create a fresh token under **Account → Access tokens**. |
88
+| Only some repositories are listed | Without a token you only see public repositories. Add the header to see your own private ones. |
89
+| Client can't connect at all | The MCP endpoint lives on the same host as the web UI — make sure `https://<your-instance>/mcp` is reachable through your instance's HTTPS proxy and you're not pointing at the legacy `/mcp/sse` path with a Streamable-HTTP client. |