Skip to content
Back to search

capalens-ia-check

Read-only checks for Intelligent Access (IA): MCP servers, OpenAPI documents, A2A Agent Cards and Agent Skills. Evidence for every result, no scores. See capalens.com for IA and the IAP draft.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/definefuture--capalens-ia-check/badge.svg)](/listings/definefuture--capalens-ia-check)

HTML

<a href="/listings/definefuture--capalens-ia-check"><img src="/api/listings/definefuture--capalens-ia-check/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Python 3.11 or newer.

pipx install capalens-ia-check            # once published to PyPI
pipx install git+https://github.com/DefineFuture/capalens-ia-check   # from the repository

Or use `pip install capalens-ia-check`, `uvx capalens-ia-check`, or the container image (see [Docker](#docker)). Add `[yaml]` (`pip install "capalens-ia-check[yaml]"`) to read YAML OpenAPI documents.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 196 lines · 2 findings marked
  1. # capalens-ia-check
  2. [![Website](https://img.shields.io/badge/website-capalens.com-0b6fbf)](https://capalens.com)
  3. [![CI](https://github.com/DefineFuture/capalens-ia-check/actions/workflows/ci.yml/badge.svg)](https://github.com/DefineFuture/capalens-ia-check/actions/workflows/ci.yml)
  4. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  5. ![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab)
  6. **Read-only checks for Intelligent Access (IA) — the MCP servers, APIs, agents and skills that AI connects to.
  7. Evidence for every result, in the spirit of the IAP evidence format. No scores.**
  8. [Website](https://capalens.com) · [IA and IAP](docs/ia-and-iap.md) · [Wiki: ideas](https://github.com/DefineFuture/capalens-ia-check/wiki) · [中文说明](README.zh-CN.md) · [Checks](docs/checks.md) · [GitHub Action](docs/github-action.md) ·
  9. [Monitoring](docs/monitoring.md) · [Report format](docs/report-format.md) · [Methodology](docs/methodology.md) ·
  10. [Related projects: positioning](docs/comparison.md)
  11. `capalens-ia-check` is the small, open-source companion of the **CapaLens** detection engine. It answers one
  12. question about an Intelligent Access (IA), quickly and repeatably: *what can be observed about it right now, against its
  13. own specification?*
  14. ```text
  15. $ capalens-ia-check mcp https://mcp.example.com/mcp
  16. [PASS ] MCP-003 Handshake returns a JSON-RPC result - initialize answered
  17. [PASS ] MCP-004 Negotiated protocol version is a published revision - protocol version 2025-11-25
  18. [FAIL ] MCP-009 Tool names follow the naming rules - 1 name(s) outside 1-128 of A-Z a-z 0-9 _ - .
  19. [REVIEW ] SEC-003 Declared tool annotations agree with the tool text - 1 tool(s): declared hints and
  20. tool text disagree (candidates, not observed actions)
  21. Summary: 15 pass, 1 fail, 1 review, 0 unknown, 1 skip | 7 request(s)
  22. ```
  23. ## IA and IAP
  24. > **IA — Intelligent Access.** In CapaLens, Intelligent Access means the specific endpoints and access
  25. > capabilities that an AI or LLM application can connect to, invoke or operate: MCP servers, APIs, CLIs, SDKs,
  26. > remote connections, agent skills. "Intelligent" describes the entry point's place in AI workflows — the service
  27. > itself need not contain a model. Being called IA does not mean being tested or safe.
  28. >
  29. > **IAP — Intelligent Access Protocol (draft).** An early proposal by the CapaLens project for a shared data
  30. > language for the capability descriptions, verification evidence and trust assessments of IA. It is not another
  31. > calling protocol and replaces neither MCP nor registries: a registry tells you *what exists*; IAP records *the
  32. > evidence for relying on it* — version, conditions, permissions, test results, check date and evidence source.
  33. > IAP is a project proposal, **not an adopted industry standard and not part of MCP**.
  34. | | IA | IAP |
  35. | --- | --- | --- |
  36. | What it is | the entry points AI uses: MCP, API, CLI, SDK, remote connections, skills, agents | a draft data language for evidence about one IA |
  37. | Question it answers | *through which entry points can an AI use which capabilities?* | *what is this IA, under which conditions, on what evidence?* |
  38. | What capalens-ia-check does with it | checks four kinds of IA material: MCP servers, OpenAPI documents, A2A Agent Cards, Agent Skills | writes machine-check evidence that follows IAP's evidence principles: version and date, `unknown` stays unknown, no composite score (no IAP records yet) |
  39. Read more: [IA and IAP](docs/ia-and-iap.md) ·
  40. [What is Intelligent Access](https://capalens.com/en/guides/what-is-intelligent-access/) ·
  41. [The IAP draft](https://capalens.com/en/guides/iap-protocol-draft/) ·
  42. [IAP evidence format](https://capalens.com/en/guides/iap-evidence-format/)
  43. ## Why another checker
  44. * **One tool, four kinds of AI integration.** A remote MCP server, the OpenAPI document behind a tool, an A2A
  45. Agent Card and an Agent Skill are checked the same way and reported in the same format.
  46. * **Read-only, local-only.** For an MCP server it sends the handshake and the `*/list` requests, one request for
  47. a method that does not exist, and ends the session. **It never calls a tool**, reads a resource or fetches a
  48. prompt, and it never sends what it finds to anyone: the security screens are word lists that run on your
  49. machine.
  50. * **Evidence, not scores.** Every result is `pass`, `fail`, `review`, `unknown` or `skip`, with the message,
  51. the evidence and the specification it was checked against. `review` means "a human should look at this" —
  52. a heuristic candidate, never a verdict. There is no score, grade or badge to game.
  53. * **Built for CI and monitoring.** Exit codes, JSON, Markdown and SARIF 2.1.0 output, a GitHub Action, and
  54. pinning of MCP tool definitions: run it on a schedule and a changed tool description (a "rug pull") becomes a
  55. review candidate.
  56. * **No dependencies.** The standard library only (PyYAML optional, for YAML OpenAPI documents).
  57. ## Install
  58. Python 3.11 or newer.
  59. ```bash
  60. pipx install capalens-ia-check # once published to PyPI
  61. pipx install git+https://github.com/DefineFuture/capalens-ia-check # from the repository
  62. ```
  63. Or use `pip install capalens-ia-check`, `uvx capalens-ia-check`, or the container image (see [Docker](#docker)).
  64. Add `[yaml]` (`pip install "capalens-ia-check[yaml]"`) to read YAML OpenAPI documents.
  65. ## Try it in ten seconds
  66. ```bash
  67. capalens-ia-check demo
  68. ```
  69. `demo` starts a local MCP server on 127.0.0.1 with a well-behaved and a deliberately risky tool set, checks
  70. both, then checks a bundled OpenAPI document, Agent Card and Agent Skill. Nothing leaves your machine. The risky
  71. server shows what failures and review candidates look like: a duplicate tool name, a session id with a space, a
  72. hidden `<IMPORTANT>` instruction to read `~/.ssh/id_rsa`, invisible Unicode, and a tool declared read-only whose
    • Warning: Contains a <important> block, a common wrapper for instructions hidden in a tool description
    • Critical: Tells the agent to read credentials and send them somewhere or keep it from the user
    • Line 90 on GitHub
  73. description deletes files.
  74. ## Use
  75. ```bash
  76. # A remote MCP server (Streamable HTTP). A token is read from an environment variable, never from the command line.
  77. export MCP_TOKEN=...
  78. capalens-ia-check mcp https://mcp.example.com/mcp --bearer-env MCP_TOKEN
  79. # An OpenAPI 3.0/3.1 document, an A2A Agent Card (a base URL reads /.well-known/agent-card.json), an Agent Skill
  80. capalens-ia-check openapi ./openapi.json
  81. capalens-ia-check agent-card https://agents.example.com
  82. capalens-ia-check skill ./skills/release-notes
  83. # Many targets at once, compared with the previous run
  84. capalens-ia-check run capalens-targets.json --baseline last-report.json --json-out report.json
  85. ```
  86. Common options:
  87. | Option | Meaning |
  88. | --- | --- |
  89. | `--format text\|json\|markdown\|sarif` | what is printed (default `text`) |
  90. | `--json-out`, `--markdown-out`, `--sarif-out FILE` | also write these files (any combination) |
  91. | `--fail-on fail\|review\|unknown\|never` | exit 1 when a result is at or above this outcome (default `fail`) |
  92. | `--baseline REPORT` | an earlier JSON report: changed MCP tool definitions become `review` (SEC-004) |
  93. | `--timeout`, `--max-requests` | per-request timeout (15 s) and request budget per target (25) |
  94. | `--bearer-env VAR`, `--header 'Name: value'` | credentials; values are sent, never printed or written to a report |
  95. | `-v` | show skipped checks and evidence |
  96. Exit codes: `0` nothing at or above `--fail-on`, `1` something is, `2` usage or input error.
  97. A targets file lists what to check; paths are relative to the file, credentials are named environment
  98. variables ([example](examples/targets-with-mcp.json)):
  99. ```json
  100. {
  101. "defaults": { "timeout": 15, "maxRequests": 25 },
  102. "targets": [
  103. { "name": "my-mcp-server", "kind": "mcp", "location": "https://mcp.example.com/mcp", "bearerEnv": "MY_MCP_TOKEN" },
  104. { "name": "my-api", "kind": "openapi", "location": "openapi.json" },
  105. { "name": "my-agent", "kind": "agent-card", "location": "https://agents.example.com" },
  106. { "name": "my-skill", "kind": "skill", "location": "skills/my-skill" }
  107. ]
  108. }
  109. ```
  110. ## What is checked
  111. 39 checks in three layers — **L0** reachability and transport, **L1** protocol and format, **L3** security
  112. candidates. The full list with references is in [docs/checks.md](docs/checks.md) (`capalens-ia-check checks`).
  113. | Kind | Checks |
  114. | --- | --- |
  115. | MCP server | HTTPS; handshake (`initialize`, or `server/discover` for the stateless 2026-07-28 revision); negotiated version; `serverInfo`; JSON-RPC ids; session id characters; `tools/list`; tool name rules and uniqueness; input schemas; pagination; `-32601` for unknown methods; capabilities match what is served |
  116. | OpenAPI | parses; 3.0/3.1; `info`; operations; unique `operationId`; path parameters declared; internal `$ref`s resolve; security schemes declared; HTTPS servers; responses (3.0) |
  117. | A2A Agent Card | parses; required fields (1.0 and 0.x cards); skills; HTTPS interfaces; security schemes declared |
  118. | Agent Skill | front matter; `name`/`description` limits; name format matches the directory; allowed fields; body size; bundled executables listed (never run) |
  119. | All kinds (L3) | prompt-injection and exfiltration wording; invisible and bidirectional characters; for MCP, tool annotations that disagree with the tool's own text, and changes since a baseline |
  120. ## In GitHub Actions
  121. ```yaml
  122. - uses: DefineFuture/capalens-ia-check@v0
  123. with:
  124. kind: openapi # mcp | openapi | agent-card | skill | run
  125. target: openapi.yaml
  126. fail-on: fail
  127. ```
  128. The action writes a Markdown summary to the run page and JSON and SARIF files you can upload to code scanning.
  129. Ready-to-copy workflows: [pull-request check](examples/github/capalens-pr.yml) and
  130. [scheduled monitoring](examples/github/capalens-monitor.yml). Details in [docs/github-action.md](docs/github-action.md).
  131. ## Docker
  132. ```bash
  133. docker build -t capalens-ia-check .
  134. docker run --rm capalens-ia-check mcp https://mcp.example.com/mcp
  135. docker run --rm -v "$PWD:/work" capalens-ia-check openapi /work/openapi.json
  136. ```
  137. ## What it does not do
  138. * It does not prove an integration is safe, or unsafe. A `pass` is what these checks observed this time; a
  139. `review` is a candidate for a human. Read [docs/methodology.md](docs/methodology.md).
  140. * It does not call tools, follow external `$ref`s, verify Agent Card signatures, run skill scripts, or test
  141. business behaviour. It is not a full conformance suite: for MCP, also run the official
  142. [conformance tests](https://github.com/modelcontextprotocol/conformance).
  143. * The security screens read English words, not meaning; deceptive text can pass and harmless text can be flagged.
  144. ## Relationship to CapaLens
  145. [CapaLens](https://capalens.com) maps AI integrations — MCP servers, APIs, agents, skills — with evidence
  146. about what they are and how they behave. Its detection engine runs a larger, four-layer pipeline with signed,
  147. versioned evidence and human review. `capalens-ia-check` takes a subset of that engine's checks and its shared
  148. heuristics (`action-heuristic/3`, `poisoning-lexicon/0.1`) and makes them easy to run anywhere. Results from
  149. this tool are not CapaLens catalogue results. Learn more at [capalens.com](https://capalens.com).
  150. ## Contributing, security, license
  151. * Contributions are welcome — new checks, false-positive reports, documentation: see
  152. [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
  153. * Report vulnerabilities privately: [SECURITY.md](SECURITY.md).
  154. * Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Copyright 2026 南京定义未来科技有限公司
  155. (Nanjing Define Future Technology Co., Ltd.).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.