A coding agent that asks “which repo holds this coordinate, and what are the dependency and vulnerability counts?” does not need mvn / npm / docker stuffed into the model context. AngusRepo exposes that as an in-process MCP read-only endpoint: the host connects, calls named tools, and the server loops back to this process’s management API for metadata projections.
Takeaway: Repo MCP is read-only end to end—eight tools prefixed
repo_by default; it does not proxy/maven,/npm,/v2, or other protocol paths; it does not download binaries, mint tokens, or run cleanup. Community does not include MCP; Team / Enterprise / Cloud follow the docs. Identity must be a portal-issued user access token (PAT); a Deploy Token (repod_) gets 401.
How console and clients wire MCP: Connect to AngusRepo via MCP. This article covers how the eight read-only tools split, why PAT and Deploy Token differ, plus rate limits and edition boundaries. Cache consistency: AngusRepo cache architecture.
1. Five read-only questions agents keep asking
In chat, the same five patterns show up:
- Locate an ingested artifact and say whether it is quarantined or already scanned.
- Inspect dependencies, declared licenses, and vulnerability counts.
- Emit client setup snippets for a repository format (password placeholders).
- Preview what an existing cleanup policy would affect (without executing).
- Read an existing security score snapshot for a repository or tenant.
Explicitly out of scope: upload, delete, publish, download, trigger scans, mint tokens. Protocol pulls keep using PAT or Deploy Token—they never enter MCP.
2. Shape: in-process endpoint + loopback
IDE / Agent
--POST {gateway}/repo/mcp--> Boot /mcp
--loopback Bearer--> /api/v1/** (GET whitelist)
An in-process endpoint reuses the permissions and audit already on REST. A separate Node that re-wraps REST would duplicate policy. Loopback has no generic path parameter, so the model cannot invent protocol or download routes.
| Item | Stance |
|---|---|
| Transport | Stateless POST; default path /mcp; via gateway {host}/repo/mcp
|
| Loopback | Base URL is the local Repo port; Bearer forwarded as-is; X-Angus-Client-Source: mcp
|
| Registration | tools only; no MCP resources / prompts / sampling |
| GM | No new GM resources; tool visibility follows existing @PPS codes |
Instance switches (edition config, aligned with user docs):
| Setting | Role |
|---|---|
angus.mcp.enabled (env ANGUS_MCP_ENABLED, defaults true when unset) |
false skips registering the endpoint; artifact hosting is unaffected |
angus.mcp.write-enabled |
Product-fixed false; no write tools |
Rate limit: at most 30 successful tools/call per account per minute; invalid args return before counting. Community does not seed the System → MCP tab and force-disables /mcp.
3. Eight tools (names follow the docs)
With a system admin or a role that holds every read permission, tools/list should show exactly eight:
| Tool | Permission notes | What it does |
|---|---|---|
repo_find_artifact |
Artifacts:VIEW |
Search by name fragment etc.; at least one filter; pageSize clamped to 1–20 |
repo_locate_version |
Artifacts:VIEW |
Exact primary-file locate; multiple hits → ambiguous + candidates, no guessing |
repo_inspect_dependencies |
Artifact fields Artifacts:VIEW; license findings also need SecurityScans:VIEW
|
Dependencies, declared licenses, vulnerability counts; does not trigger scans |
repo_list_repositories |
Repositories:VIEW |
Visible repos, no settings |
repo_client_setup |
Repositories:VIEW |
Same templates as the console; passwords are placeholders |
repo_artifact_security |
Scan history etc. also need SecurityScans:VIEW
|
Quarantine, existing vulnerability counts and scan history; does not trigger scans |
repo_repository_score |
SecurityScans:VIEW |
Repo/tenant score snapshot—not a single-package score |
repo_cleanup_preview |
CleanupPolicies:VIEW |
GET preview only; no execution records |
Result projections deliberately drop downloadUrl, checksums, README, and full license text to shrink model misuse and leak surface.
Not in the list: repo_search, repo_compare_versions (follow-ups, not registered by default), repo_invoke_read, repo_connection_check, or any publish / delete / execute cleanup / mint token.
Empty secure or scanTrust=UNKNOWN means not scanned yet, not “safe.” Admission gate is off by default; Repo enforcement vs Security engines matches the product FAQ.
4. Auth boundary (easy to get wrong)
| Credential | Result |
|---|---|
| Portal-issued user access token (PAT) | Can enter MCP; tool set narrows with role |
repod_ Deploy Token |
401, no tool list |
| OAuth refresh token / other product tokens | 401 |
| No Bearer | 401 (avoid collapsing into in-tool errors that make the model blind-retry) |
Visibility equals that user’s /api/v1 scope—same as the console. MCP does not re-interpret protocol-path repo:read / repo:write. repo:write on a PAT means protocol write—not MCP write.
Personal tokens: avatar → Me (/profile). CI should use a service account—do not commit a personal login into the repo.
5. Host wiring (minimal snippet aligned with the manual)
Put the token in an env var—never in the repo:
{
"mcpServers": {
"angus-repo": {
"url": "https://<gateway-host>/repo/mcp",
"headers": { "Authorization": "Bearer ${ANGUS_REPO_TOKEN}" }
}
}
}
| Host | Config file (trust each host’s docs) |
|---|---|
| Cursor | Project .cursor/mcp.json or user ~/.cursor/mcp.json
|
| Claude | claude_desktop_config.json |
| VS Code | Workspace .vscode/mcp.json
|
Stdio-only hosts can forward with @anguskit/mcp --product repo; that process reads ANGUS_TOKEN / ANGUS_BASE_URL—not the same names as ANGUS_REPO_TOKEN above. If the default npm source lacks the package, docs suggest https://repo.anguskit.com/npm/npm-public/. Full host table: MCP docs.
5.1 One real dialogue: user ask → tool → expected shape
| Step | Content |
|---|---|
| User asks | Where is log4j-api 2.24.1? Quarantined? |
| Should call |
repo_locate_version first (coordinate/name + version); then repo_artifact_security if vulnerability counts and quarantine fields are needed (or use security projection fields already on the locate result—trust the live response) |
| Expected fields / shape | Artifact id as a decimal string; repo name, format, version checkable; multiple primary files → ambiguous with candidates—model must not pick one
|
| Must not appear |
downloadUrl, full checksums, full license text; must not trigger a new scan |
After connect, have the assistant tools/list to confirm exactly eight repo_*, then smoke one real Maven coordinate with repo_locate_version.
6. Short industry contrast
| Shape | Example | Versus AngusRepo (one line) |
|---|---|---|
| Hosted intel MCP | Sonatype Guide | Public component intel—does not read customer repos |
| Wide platform tool surface | JFrog Platform MCP | Includes writes; AngusRepo stays narrow read-only |
| In-process narrow tools | AngusRepo | Loopback to this process’s REST; protocol paths isolated |
Contrast explains product trade-offs—not a procurement ranking. Trust each vendor’s docs of the day for detail.
7. Boundaries and failure table
| Symptom | Cause | Fix |
|---|---|---|
| Cannot connect | Community / enabled=false / wrong URL |
Change edition or enable; check /repo/mcp
|
| 401 | Used repod_ or a refresh token |
Switch to a PAT from Me |
| Few tools | Role missing permission codes | Add Artifacts:VIEW etc. per docs |
| Agent wants a jar | Thought MCP proxies protocol | Use mvn/npm/docker on protocol paths |
| Treats repo score as package score | Misread repo_repository_score
|
Use vulnerability counts and quarantine on the artifact |
ambiguous |
Multiple primary files for one coordinate | List candidates for a human; do not pick |
rate_limited |
Over 30 calls/minute | Back off; merge questions |
FAQ
Can MCP delete packages or run cleanup?
No. Write switch stays off; cleanup is preview only.
How does this relate to Skills?
Skills describe which artifact risks to ask about; MCP provides callable query tools. Both can be used together (product doc stance).
Why not a generic read-only gateway?
Named tools keep the loopback whitelist small, avoid exposing the whole admin API to the model, and make projection redaction easier.
Why can Deploy Tokens not connect MCP?
repod_ is a single-repo CI credential. Letting it call management-plane MCP would turn an automation token into a chat identity—401 before auth proceeds.
Takeaways
- Core trade-off: read-only, eight tools, loopback REST, protocol paths isolated.
- Wiring core: gateway
/repo/mcp+ PAT; Deploy Token will not work. - Community lacks this capability; when you need it, follow Team/Enterprise/Cloud docs and console switches.
Reference articles
- Connect to AngusRepo via MCP: https://www.anguskit.com/en/docs/repo/get-started/mcp
- AngusRepo product introduction: https://www.anguskit.com/en/docs/repo/get-started/introduction
- AngusRepo cache architecture: https://www.anguskit.com/en/blog/angusrepo-cache-architecture
- Artifact admission for vulnerabilities and licenses: https://www.anguskit.com/en/blog/artifact-repo-vulnerability-license-scanning
- Deploy Token and ACL: https://www.anguskit.com/en/blog/angusrepo-deploy-token-pat-acl-guide
Top comments (0)