# MCP-FIRST MANIFEST, MACHINE EDITION
# A normative, vendor-neutral specification for auditing and building
# agent-controllable software. Written for AI agents and automated checkers.
#
# Canonical URL: https://mcp-first.ai/manifest.ai
# Version: 1.0.0
# License: public, free to use and reference.
# Keywords (RFC 2119): MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

## 0. HOW AN LLM SHOULD USE THIS DOCUMENT

This document is the single source of truth needed to audit an MCP server or
capability layer for MCP-first conformance. It is self-contained. Read every
rule (R1..R40), evaluate the target system against each, and emit a verdict
per rule using the OUTPUT CONTRACT in section 7.

Minimal usage prompt (give this to an LLM together with access to the target):

  "Audit the following MCP server against https://mcp-first.ai/manifest.ai.
   For every rule R1..R40 return: id, verdict (pass|fail|partial|n/a) and a
   one-line reason. End with conformance_score = pass / applicable. List the
   top 3 critical failures first."

## 1. DEFINITIONS

- CAPABILITY: a typed, permission-checked unit of system behavior. One of:
  TOOL (an action), RESOURCE (readable data/context), WORKFLOW (a guided
  multi-step procedure).
- ADAPTER: an interface (web UI, mobile, CLI, MCP server) that calls
  capabilities. Adapters contain no business logic.
- RISK LEVEL: one of low | medium | high | critical | restricted | forbidden.
- CONFIRMATION GATE: a required human approval before execution.
- PRINCIPAL: the resolved identity context = (human user, MCP client, agent
  identity, delegated user, tenant).

## 2. CORE ARCHITECTURE RULES

R1  (MUST)      Every externally meaningful behavior MUST be exposed as a
                CAPABILITY (tool, resource, or workflow). If the software can
                do it, the capability layer MUST be able to describe it.
R2  (MUST)      Business logic MUST live in a domain/action layer, NOT in the
                MCP server and NOT in any UI. The MCP server MUST be an adapter.
R3  (MUST)      All adapters (UI, mobile, CLI, MCP, API) MUST invoke the SAME
                action layer. No interface may have a private code path.
R4  (MUST)      A single authorization function MUST decide access:
                can(principal, action, resource, context). No second, divergent
                policy may exist in the MCP server or UI.
R5  (SHOULD)    Each domain entity SHOULD offer: list, search, get, create,
                update, archive, audit, permissions, related, and
                recommended_next_actions. Hard delete SHOULD be replaced by
                archive unless deletion is a deliberate, protected capability.

## 3. CAPABILITY CONTRACT RULES

R6  (MUST)      Every tool MUST declare a typed INPUT schema.
R7  (MUST)      Every tool MUST declare a typed OUTPUT schema.
R8  (MUST)      Every tool MUST declare an explicit ERROR / failure-mode set.
R9  (MUST)      Every tool MUST declare its required permission scopes.
R10 (MUST)      Every tool MUST declare a RISK LEVEL (section 4).
R11 (MUST)      Every tool MUST declare whether autonomous execution is allowed.
R12 (SHOULD)    Every tool SHOULD declare its side effects and the audit event
                it emits.
R13 (SHOULD)    Tools SHOULD be idempotent where the operation allows it.
R14 (SHOULD)    High-impact or bulk tools SHOULD provide a dry-run mode that
                returns the projected effect without performing it.
R15 (MUST NOT)  Tools MUST NOT accept or return untyped, free-form blobs in
                place of a declared schema.

## 4. RISK MODEL (NORMATIVE)

R16 (MUST)      Risk levels MUST be one of: low, medium, high, critical,
                restricted, forbidden.
R17 (MAY)       low: MAY run autonomously.
R18 (MAY)       medium: MAY run autonomously when scope and context are
                unambiguous.
R19 (SHOULD)    high: SHOULD require a confirmation gate.
R20 (MUST)      critical: MUST require a confirmation gate; MUST support
                step-up authentication.
R21 (MUST)      restricted: MUST NOT be placed into AI context except as
                redacted, purpose-limited fields.
R22 (MUST NOT)  forbidden: MUST NOT be readable or callable by an AI agent at
                all (e.g. raw secrets, passwords, private keys, raw access
                tokens, full unscoped data export, disabling the audit log).
R23 (MUST)      External communication (e.g. send external email), bulk
                operations, permission changes, payments, user/tenant deletion
                MUST be classified critical at minimum.

## 5. AUTHENTICATION & AUTHORIZATION RULES

R24 (MUST)      MCP clients MUST authenticate via OAuth 2.1 Authorization Code
                with PKCE (or stronger). Access tokens MUST be short-lived;
                refresh tokens MUST rotate.
R25 (SHOULD)    Sensitive deployments SHOULD enforce a client allowlist and
                strict redirect-URI validation.
R26 (MUST)      An agent MUST act within a delegated user context or an
                explicitly configured service role. An agent MUST NOT receive
                blanket system privileges.
R27 (MUST)      Tool VISIBILITY MUST be filtered at discovery time by principal,
                role, scope, and tenant. A principal MUST NOT see tools it may
                not use.
R28 (MUST)      Multi-tenant systems MUST bind every access to a tenant scope.
R29 (MUST)      Effective AI access MUST be a function of: user permission +
                agent permission + client trust + resource sensitivity +
                purpose + context + confirmation state. "User can see it" alone
                MUST NOT grant AI access.

## 6. CONTROL, CONFIRMATION & AUDIT RULES

R30 (MUST)      Risky and irreversible actions MUST require explicit human
                confirmation before execution (human-in-the-loop).
R31 (MUST)      The confirmation surface MUST show: what, why, which data,
                external effects, who is affected, reversibility, and outcome.
R32 (MUST)      Critical actions MUST support step-up authentication (re-auth,
                TOTP, passkey, admin or four-eyes approval).
R33 (SHOULD)    The system SHOULD persist a consent ledger: principal, tool,
                input summary, risk level, approval method, time, expiry.
R34 (MUST)      Every executed tool call MUST emit an audit event with at least:
                tool, principal, tenant, risk level, result, timestamp.
R35 (MUST)      Sensitive inputs in audit records MUST be hashed, redacted, or
                summarized, never stored in clear when not necessary.
R36 (MUST)      AI-facing data MUST be redacted / context-filtered to the
                minimum needed for the task; full records MUST NOT be dumped
                into model context by default.
R37 (SHOULD)    Large files/datasets SHOULD NOT be loaded into AI context
                unchecked.
R38 (SHOULD)    The system SHOULD apply rate limits and prompt-injection
                defenses on agent-reachable surfaces.
R39 (SHOULD)    Tool metadata exposed at discovery SHOULD be validated /
                signed to prevent tampering.
R40 (MUST)      The audit log itself MUST NOT be disable-able by an AI agent.

## 7. OUTPUT CONTRACT (FOR AUTOMATED AUDITS)

Return JSON:

{
  "target": "<name or URL of audited system>",
  "manifest_version": "1.0.0",
  "results": [
    { "id": "R1", "verdict": "pass|fail|partial|n/a", "reason": "<one line>" }
    // ... one object per rule R1..R40
  ],
  "critical_failures": ["R22", "..."],
  "conformance_score": "<count(pass) / count(applicable)>",
  "summary": "<2-3 sentence verdict>"
}

Rules with verdict "fail" on any MUST/MUST NOT are blocking: a system with any
blocking failure is NOT MCP-first conformant, regardless of score.

## 8. CONFORMANCE LEVELS

- LEVEL 0 (NON-CONFORMANT): one or more MUST/MUST NOT rules fail.
- LEVEL 1 (BASELINE): all MUST/MUST NOT pass; some SHOULD may fail.
- LEVEL 2 (RECOMMENDED): all MUST and all SHOULD pass.

# END OF MANIFEST