[DBIP] Add per-variable types for required self-hosted MCP configuration

[taizaki69]

Proposal type

Add column.

Affected scope (files/folders/chains)

references/offers/mcpservers.csv; corresponding listings/**/mcpservers.csv headers; MCP schema and column metadata on json-tools; MCP Servers wiki. Pilot on the existing Filecoin Onchain Cloud offer and its Filecoin listing.

Motivation / problem statement

At data commit e83cde059024fc5cfaf9881f5435c332905d54d4, the filecoin-onchain-cloud-mcp offer has authType=API Key and selfHostedRequiredEnvVars=["PRIVATE_KEY"]. The provider's configuration documentation identifies PRIVATE_KEY as a wallet private key, not a provider-issued API key. The Filecoin listing inherits the canonical offer.

The existing fields identify required variable names and a server-level authentication label, but do not classify the purpose of each configuration variable. A wallet signing key, API-service credential, and non-secret setting should not have to be distinguished by guessing from their names. Per-variable metadata would let setup interfaces explain what a local server requires, separately from how a client authenticates to it.

This is a data-model improvement, not a claim of a credential leak or exploitable vulnerability.

Detailed proposal

• Category/table: mcpservers
• Column name: selfHostedEnvVarTypes
• Change type: add, optional
• Definition: a JSON object classifying documented required environment variables for a self-hosted MCP server.
• Allowed labels: api-key, wallet-private-key, wallet-mnemonic, access-token, other-secret, non-secret.

For the Filecoin offer:

{"PRIVATE_KEY":"wallet-private-key"}

Only variable names and classification labels belong in this field. Never store credential values, private keys, recovery phrases, or tokens.

Validation and unknown values

1. A nonempty map is valid for hostingType=Self-hosted. Each key must exactly match a name in the resolved selfHostedRequiredEnvVars list; matching is case-sensitive.
2. Reject malformed JSON, duplicate object members, non-object values, and labels outside the allowed set. Duplicate members must be detected before ordinary JSON parsing discards them.
3. Partial maps are permitted. Missing metadata means unclassified, never "no secrets" or "API key by default." Use other-secret only when documentation establishes that the variable is a secret of another kind.
4. Classify variables from first-party documentation, not from names or HTTP responses. Schema validation establishes shape, not the truth of a provider claim.

Compatibility and inheritance

Keep authType and selfHostedRequiredEnvVars unchanged. The new field describes configuration independently; it does not redefine the legacy authentication field. Consumer documentation should distinguish the two rather than present a signing key as an API credential.

Follow the existing normalize and resolve_offers behavior: blank and whole-cell null normalize to None and inherit from the referenced offer. An explicitly supplied object replaces the inherited map as a whole; it is not merged key by key. An explicit {} clears inherited classifications without changing the required-variable list. Validate the final map against the final required-variable list after resolution.

The inheritance-documentation discrepancy is already reported in #3293 and #3301; it is not a new finding claimed here.

Rollout

Coordinate the schema, metadata, CSV-header, wiki, and consumer changes after approval, preserving validation of legacy rows during the transition. Start with the documented Filecoin example and leave unverified classifications blank. The implementation should run the repository's full conversion and validation pipeline before merge.

Acceptance criteria

• The Filecoin wallet key can be classified explicitly as a wallet signing credential, separately from an API key.
• Existing rows remain valid without invented classifications or changed legacy values.
• Duplicate members, undeclared variable names, unsupported labels, and malformed maps are rejected.
• Listing inheritance and whole-map overrides follow the existing converter semantics.
• No actual credential values are collected or stored by this change.

Validation and related work

An offline reference validator and 16 standard-library unittest methods have been prepared; all 16 passed on September 6, 2026. They cover the proposed CSV-text representation, including legacy rows, blank/null/empty values, partial maps, case sensitivity, duplicate members, malformed JSON, undeclared names, labels, and hosting constraints. This is a local design test suite, not an upstream integration test or a production-tested patch.

#2976 proposes alternative client authentication methods. This proposal instead classifies individual required self-hosted configuration variables; it does not claim the authentication-method proposal as new. A targeted issue search for selfHostedEnvVarTypes returned no matches, but that is not an exhaustive nonduplication guarantee.

Contact (optional)

Please use this issue for review and clarification.

Rewards address (optional)

0x688992f4a26f5b740fc758ede2dfabfd97856585