`mcp`¶

An mcp is how an agent gets a structured tool surface: a server that speaks the Model Context Protocol, or the client configuration that points a harness at such a server.

An MCP component answers the question: which external tool interface is connected?

It does not answer "how should the agent use that tool?" (skill or instruction), "which package extends the harness?" (plugin), or "which named shortcut do I type?" (command).

Two different MCP objects

This page covers both native roles discovery can report. They share kind mcp and they are not the same object.

Object	`native_role`	What discovery does
MCP server package	`mcp_server`	`harness_id=null`; proves a package chain; never runs the server
Plugin `.mcp.json`	`mcp_client_config`	proves itself by name; discovery does not open it
Servers inside a settings file	`mcp_client_config`	file is also a `setting`; only server names are read

A plugin .mcp.json is client config, not a server. Tokens, access bearing URLs, command, args, headers, and env never enter discovery output, passports, logs, or fixtures.

Pi 1.0.0 has native mcp.json, but ai_stp discovery and the pinned provider profile do not yet support that route. The machine table reports mcp_config_not_integrated.

Neighbours¶

Kind	The main difference
`plugin`	a plugin may carry `.mcp.json` client config; the server package is still `mcp`
`setting`	Codex, OpenCode, and Grok Build keep client servers inside a file also declared as `setting`
`skill`	a skill explains when and how to use a tool; MCP is the tool interface
`instruction`	standing rules about tools stay text; they do not start a server
`hook`	a hook fires on an event; MCP waits to be called as a tool
`command`	a command is a named shortcut; MCP is a protocol surface
`agent`	a role may be allowed to use MCP tools; the server is not the role

Choose mcp when the agent must call an external tool through MCP. Choose plugin when you are shipping a harness package that may include client config. Choose setting when you are pinning parameters that are not server entries.

Recommended package structure¶

--language for an MCP server is one of python, typescript, javascript, rust, go, or dart-flutter. The kind is executable.

An MCP server package belongs to no single harness (harness_id=null). Discovery does not guess from an mcp substring. It requires a consistent chain:

Python: pyproject.toml → MCP SDK dependency → project.scripts → exact module import of the SDK.
TypeScript: package.json → SDK dependency → bin / script source → exact SDK import.

github-issues/                     # published server package
├── pyproject.toml                 # dependencies include mcp or fastmcp
└── src/
    └── github_issues/
        └── server.py              # project.scripts target; imports the SDK

github-issues/                     # TypeScript server package
├── package.json                   # @modelcontextprotocol/sdk or fastmcp
└── src/
    └── index.ts                   # bin/script entry; imports the SDK

When you start from ai_stp, start the author intent. Do not type component scaffold plan. The authoring directory is wider than the published package: discover / adopt transfer source/ when portable and projections/<harness>/ when a harness was selected, not the whole tree. The scaffold plants source/mcp.json plus a language entry; a discoverable server still needs the manifest chain above. Claude Code mcp is refused: there is no provider-owned MCP surface.

github-issues/                     # component-scaffold/6
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
└── source/
    ├── mcp.json
    └── src/main.py                # python handler; add the package manifest

Everyday:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Expert recovery (already-held digest):

ai-stp component scaffold plan \
  --type mcp \
  --language python \
  --harness portable \
  --name github-issues \
  --output ./github-issues \
  --json

ai-stp component scaffold apply \
  --type mcp \
  --language python \
  --harness portable \
  --name github-issues \
  --output ./github-issues \
  --expected-plan-digest <digest> \
  --json

For required_env, record names and purposes in the passport, never values. Secrets, tokens, and passwords do not go into a passport.

There is no ai-stp component mcp validate. Structural readiness is component passport validate. Kind-specific specification checking exists only for skill.

Standards and frameworks¶

Model Context Protocol — the independent standard.
Build-server guide used as discovery layout_source for server packages: Build an MCP server.
SDK names discovery will accept in the dependency chain: Python mcp or fastmcp; TypeScript @modelcontextprotocol/sdk or fastmcp.
NVIDIA SkillSpector and Cisco Skill Scanner are skill scanners. They do not validate MCP.

Client layouts are declared per harness. Cite layout_source on the finding rather than guessing a vendor path.

Native layouts per harness¶

Discovery only reports layouts that are declared. Exact paths on a machine come from the author intent envelope. Each finding carries layout_source. If classification is uncertain, show that field; do not guess a neighbour's path.

From the discovery matrix:

Harness	Global	Project	Notes that are in the discovery contract
Claude Code	yes	yes	plugin-internal `.mcp.json` is `mcp_client_config`; discovery does not open it
Codex	names in `config.toml`	names in `config.toml`	file is also a `setting`; key `mcp_servers`; existence is not enough
Pi	not integrated	not integrated	native `mcp.json` exists in Pi 1.0.0; ai_stp reports `mcp_config_not_integrated`
OpenCode	names in `opencode.json` / `opencode.jsonc`	same files	file is also a `setting`; key `mcp`; existence is not enough
Grok Build	names in `config.toml`	names in `config.toml`	file is also a `setting`; key `mcp_servers`; existence is not enough
Cursor	names in `mcp.json`	names in `.cursor/mcp.json`	declared `mcpServers` key; adjacent files do not qualify
Antigravity	yes	yes
`undefined`	portable conventions	portable conventions	not a harness; automatic install is not considered safe
(server package)	n/a	n/a	`harness_id=null`; Python or TypeScript chain as above

Codex, OpenCode, and Grok Build keep client servers inside a file also declared as setting. File existence is not enough: at least one server must be declared under the key. One file can produce two findings (setting + mcp). Only server names enter evidence_refs (for example mcp_servers.github). Values next to a name — command, arguments, URL, headers, environment — are neither read nor returned.

A plugin .mcp.json proves itself by name, so discovery does not open it. Working servers for Claude Code packs reside there; guessing a different home file is not a layout.

Expert recovery — everyday authoring is the author intent:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Do not type component discover. The engine finds the native tree.

If the same path is both a setting and an mcp, name --kind on adopt. Do not adopt the file twice under guessed kinds.

Versions are `X.Y`, not SemVer¶

A published MCP version is immutable and has the form X.Y. There is no patch number. Changing the server, its entry point, or the client declaration is a new version. Updating MCP inside a setup is a new setup version.

ai-stp component version list --id <stable_id> --json
ai-stp component version release --id <stable_id> --json

--major opens the next major line. A major line is a separate access boundary.

What `ai_stp` checks¶

The catalog percent and the required-versus-optional split are explained on Security checks. For MCP, expect at least:

structure, digest, license, tags, source repository;
bounded unpack and path denylist;
secret scanning (secrets_heuristic, and Gitleaks when enabled);
prompt-injection and hidden-content rules;
mcp_config_static (schema, transport policy, capability);
language SAST and SCA when scripts and lockfiles are present.

A passed scan reduces known risk. It is not a guarantee that the server is harmless. Required checks that fail or cannot run block publication.

Before install, also look at:

Check	Why it matters
`native_role`	a client config is not a server; a server is not a plugin
Required permissions	MCP widens what the agent can reach
How secrets are supplied	names in the passport, values in the environment or OS store
Who is the author	a verified author does not make the server automatically safe
Which `X.Y` is pinned	updating MCP makes a new version of the setup
Trust line	`experimental` needs explicit consent

author_verified and component_verified are independent. Neither is a safety guarantee.

Only commands that exist. Flags always from the CLI pages, and always --json. The executable is ai-stp (package ai-stp-cli). There is no component inspect and no setup show. The only kind-specific validate is ai-stp component skill validate.

This kind, specifically: there is no component mcp validate. Use passport validation.

ai-stp component passport validate --id <stable_id> --json

Author, adopt, publish:

ai-stp task start --intent author --idempotency-key author-session-01 --json
ai-stp task start --intent publish --idempotency-key publish-session-01 --json

When the finding is also a setting file:

Expert recovery:

ai-stp component adopt --path <source_path> --kind mcp --json

Install:

ai-stp task start --intent install --idempotency-key install-session-01 --json

Expert catalog inspect:

ai-stp registry search --kind component --query <name> --json

An MCP component can also be an embedded member of a compose manifest. See Setups.

How an MCP component moves through `ai_stp`¶

AuthorCatalogCompilerProvider

The author publishes the server or client config from a public GitHub source, or imports it locally. The version pins an exact commit and subpath. Secret values stay out of the tree.

The catalog shows what it is for, the supported harnesses, the required permissions, the author's trusted status and the component's own independent status.

The compiler checks that the MCP object can be built into the chosen setup and that its file structure suits the provider's projection.

The provider registers the native client entry or ships the server package only after a plan, a digest and a confirmation. It does not copy tokens from the passport — there are none.

Red flags¶

Treating plugin .mcp.json as if it were the server package.
Opening .mcp.json or a settings MCP block to "check" for tokens — discovery already refuses to read those values.
Pi MCP installation claimed before discovery and the public provider profile support the native mcp.json route (mcp_config_not_integrated).
A config.toml / opencode.json with no servers under the key, labelled as MCP because the file exists.
Unpinned npx / uvx launchers, or command/args/URL/headers/env stored in the passport.
Live tokens, private keys, or .env bodies in the package.
experimental trust line without consent allow.
Harness not in the component's compatibility list.
"Latest" or a branch name instead of an exact X.Y and commit.
Treating author_verified as component_verified.
Skill scanners cited as if they validated this kind.

Can an MCP component be used without publishing it

Yes. Your own, imported or exactly pinned MCP object can be used after local checks. It does not thereby become platform-verified, and it must be shown as exactly what it is: a local or pinned object (local_owner_or_pinned).

Author checklist¶

Scaffold with --type mcp and a real --language (not none).
For a server, complete the Python or TypeScript chain: manifest, SDK dependency, declared entry, exact SDK import. Do not run the server to "prove" it.
For client config, keep values that bear access out of the artifact. Record env names only.
Declare filesystem, network, and credential needs in the passport.
Register the directory through ai-stp task start --intent author --idempotency-key author-session-01 --json. Expert component discover / component adopt remain for recovery.
Pin an exact public GitHub commit and subpath. No secrets in the tree.
component passport validate → component version release to mint immutable X.Y.
Publish through the publication path. In a setup, pin that X.Y.

Related: Authoring, Components, plugin, setting.

mcp¶

Neighbours¶

Recommended package structure¶

Standards and frameworks¶

Native layouts per harness¶

Versions are X.Y, not SemVer¶

What ai_stp checks¶

Related CLI commands¶

How an MCP component moves through ai_stp¶