@manifest-network/manifest-mcp-node

v0.23.0

Published

11 days ago

Node.js MCP servers for Manifest Network with stdio transport and keyfile wallet

0High
0Medium
0Low

fmorency_

manifest-build

mcp cosmos blockchain manifest stdio

@manifest-network/manifest-mcp-node

Node.js CLI entry points for the Manifest MCP servers with stdio transport and encrypted keyfile wallet.

Provides five binaries:

manifest-mcp-chain -- Chain MCP server (6 tools, +1 optional request_faucet: queries, transactions, fee estimation, module discovery)
manifest-mcp-lease -- Lease MCP server (8 tools: credit balance, funding, lease queries, custom-domain claim/lookup, SKUs, providers)
manifest-mcp-fred -- Fred MCP server (12 tools, plus 3 resources & 3 prompts: catalog, deployment readiness, manifest preview, deployment, ready polling, status, logs, restart, update, restore, diagnostics, releases)
manifest-mcp-cosmwasm -- CosmWasm MCP server (2 tools: MFX-to-PWR rate query, token conversion)
manifest-mcp-agent -- Agent MCP server (5 orchestrated tools: 3 broadcasting tools — deploy, manage-domain, close-lease — drive MCP elicitation and require an elicitation-capable host; 2 read-only tools — lookup-domain, troubleshoot — run on any host)

Setup

Requires Node.js >= 22.19.0 (declared via engines).

# From the monorepo root
npm install
npm run build

Wallet setup

All five servers need a wallet to sign transactions. Choose one of the options below.

Option A -- Generate a new keyfile (recommended)

npx -y -p @manifest-network/manifest-mcp-node manifest-mcp-chain keygen

All CLIs share the same keyfile (~/.manifest/key.json), so any of the five commands works for keygen and import. You will be prompted for an encryption password. The keyfile is written with mode 0600.

keygen prints the generated 24-word recovery phrase once, before exiting. Write it down and store it offline. The keyfile is encrypted with your password and nothing else on the machine holds the seed — so the recovery phrase is the only thing that survives a forgotten password or a lost keyfile.

Option B -- Import an existing mnemonic

npx -y -p @manifest-network/manifest-mcp-node manifest-mcp-chain import

You will be prompted for your mnemonic (any valid BIP-39 length: 12, 15, 18, 21, or 24 words) and an encryption password. The wallet is derived from the mnemonic, encrypted, and stored in the same keyfile location. The raw mnemonic is not retained.

Option C -- Mnemonic via environment variable (fallback)

Set COSMOS_MNEMONIC in your .env or shell environment. This is used only when no keyfile exists.

Wallet resolution order

If the keyfile exists at the path specified by MANIFEST_KEY_FILE (default ~/.manifest/key.json), use it
Otherwise, if COSMOS_MNEMONIC is set, use it
Exit with an error if neither is available

CLI reference

The five binaries below are shipped by the @manifest-network/manifest-mcp-node package. They are unscoped bin names, not package names: they are on PATH after a global or local install of that package, but npx <bin-name> alone would resolve the bin name as a package and fail. To run one without installing, name the package explicitly and select the bin:

npx -y -p @manifest-network/manifest-mcp-node <bin-name> [subcommand]

<bin-name> is any of the five listed below. The subcommand is optional and takes the same values as the PATH-installed form: omit it to start that MCP server on stdio (this is the form the Claude Desktop config below uses), or pass keygen / import / export for key management.

manifest-mcp-chain                Start the chain MCP server (stdio)
manifest-mcp-chain keygen         Generate a new encrypted keyfile
manifest-mcp-chain import         Import a mnemonic into an encrypted keyfile

manifest-mcp-lease                Start the lease MCP server (stdio)
manifest-mcp-lease keygen         Generate a new encrypted keyfile
manifest-mcp-lease import         Import a mnemonic into an encrypted keyfile

manifest-mcp-fred                 Start the fred MCP server (stdio)
manifest-mcp-fred keygen          Generate a new encrypted keyfile
manifest-mcp-fred import          Import a mnemonic into an encrypted keyfile

manifest-mcp-cosmwasm             Start the cosmwasm MCP server (stdio)
manifest-mcp-cosmwasm keygen      Generate a new encrypted keyfile
manifest-mcp-cosmwasm import      Import a mnemonic into an encrypted keyfile

manifest-mcp-agent                Start the agent MCP server (stdio)
manifest-mcp-agent keygen         Generate a new encrypted keyfile
manifest-mcp-agent import         Import a mnemonic into an encrypted keyfile

Every CLI also accepts export, which prints the keyfile's recovery phrase after asking for its password (manifest-mcp-chain export, and so on).

Recovering the mnemonic

keygen shows the recovery phrase when it generates the wallet. If you generated a keyfile before that behaviour existed — or you simply did not write the phrase down — recover it with the keyfile's password:

npx -y -p @manifest-network/manifest-mcp-node manifest-mcp-chain export

The phrase is printed to stderr, alongside the prompts, so a plain > redirect will not capture it into a file by accident. If the password itself no longer works, see the decryption entry in docs/troubleshooting.md — a keyfile created by an older release may have been encrypted with a trailing newline captured from a paste.

MCP client integration

Claude Desktop

Add the following to your claude_desktop_config.json:

Replace the placeholder values below with your actual chain ID, RPC/REST endpoint, gas price, and keyfile password.

{
  "mcpServers": {
    "manifest-chain": {
      "command": "npx",
      "args": ["-y", "-p", "@manifest-network/manifest-mcp-node", "manifest-mcp-chain"],
      "env": {
        "COSMOS_CHAIN_ID": "your-chain-id",
        "COSMOS_RPC_URL": "https://your-rpc-endpoint/",
        "COSMOS_GAS_PRICE": "0.01umfx",
        "MANIFEST_KEY_PASSWORD": "your-keyfile-password"
      }
    },
    "manifest-lease": {
      "command": "npx",
      "args": ["-y", "-p", "@manifest-network/manifest-mcp-node", "manifest-mcp-lease"],
      "env": {
        "COSMOS_CHAIN_ID": "your-chain-id",
        "COSMOS_RPC_URL": "https://your-rpc-endpoint/",
        "COSMOS_GAS_PRICE": "0.01umfx",
        "MANIFEST_KEY_PASSWORD": "your-keyfile-password"
      }
    },
    "manifest-fred": {
      "command": "npx",
      "args": ["-y", "-p", "@manifest-network/manifest-mcp-node", "manifest-mcp-fred"],
      "env": {
        "COSMOS_CHAIN_ID": "your-chain-id",
        "COSMOS_RPC_URL": "https://your-rpc-endpoint/",
        "COSMOS_GAS_PRICE": "0.01umfx",
        "MANIFEST_KEY_PASSWORD": "your-keyfile-password"
      }
    },
    "manifest-cosmwasm": {
      "command": "npx",
      "args": ["-y", "-p", "@manifest-network/manifest-mcp-node", "manifest-mcp-cosmwasm"],
      "env": {
        "COSMOS_CHAIN_ID": "your-chain-id",
        "COSMOS_RPC_URL": "https://your-rpc-endpoint/",
        "COSMOS_GAS_PRICE": "0.01umfx",
        "MANIFEST_KEY_PASSWORD": "your-keyfile-password",
        "MANIFEST_CONVERTER_ADDRESS": "manifest1..."
      }
    },
    "manifest-agent": {
      "command": "npx",
      "args": ["-y", "-p", "@manifest-network/manifest-mcp-node", "manifest-mcp-agent"],
      "env": {
        "COSMOS_CHAIN_ID": "your-chain-id",
        "COSMOS_RPC_URL": "https://your-rpc-endpoint/",
        "COSMOS_GAS_PRICE": "0.01umfx",
        "MANIFEST_KEY_PASSWORD": "your-keyfile-password"
      }
    }
  }
}

The agent server's three broadcasting tools drive MCP elicitation, so they need an elicitation-capable host (Claude Code >= 2.1.76). Its two read-only tools run anywhere. See the tool table below.

If you use a mnemonic instead of a keyfile, replace MANIFEST_KEY_PASSWORD with COSMOS_MNEMONIC.

Query-only mode (REST/LCD)

To use query-only mode without transaction signing, replace COSMOS_RPC_URL and COSMOS_GAS_PRICE with COSMOS_REST_URL:

{
  "mcpServers": {
    "manifest-chain": {
      "command": "npx",
      "args": ["-y", "-p", "@manifest-network/manifest-mcp-node", "manifest-mcp-chain"],
      "env": {
        "COSMOS_CHAIN_ID": "your-chain-id",
        "COSMOS_REST_URL": "https://your-rest-endpoint/",
        "MANIFEST_KEY_PASSWORD": "your-keyfile-password"
      }
    }
  }
}

A wallet is still required at startup even in query-only mode. Transaction tools will return an INVALID_CONFIG error.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | COSMOS_CHAIN_ID | Yes | -- | Chain ID (e.g. manifest-ledger-beta) | | COSMOS_RPC_URL | One of COSMOS_RPC_URL or COSMOS_REST_URL required | -- | RPC endpoint URL (HTTPS required; HTTP allowed for localhost) | | COSMOS_GAS_PRICE | Required when COSMOS_RPC_URL is set | -- | Gas price with denom (e.g. 0.01umfx) | | COSMOS_REST_URL | One of COSMOS_RPC_URL or COSMOS_REST_URL required | -- | LCD/REST endpoint URL for query-only mode | | COSMOS_GAS_MULTIPLIER | No | 1.5 | Gas simulation multiplier (must be >= 1) | | COSMOS_MAX_GAS | No | 50000000 | Absolute per-tx gas-limit ceiling; a broadcast whose ceil(simulate × multiplier) exceeds it aborts with GAS_LIMIT_EXCEEDED; -1 disables | | COSMOS_ADDRESS_PREFIX | No | manifest | Bech32 address prefix | | MANIFEST_KEY_FILE | No | ~/.manifest/key.json | Path to the keyfile (encrypted, or a plaintext mnemonic loaded with a warning) | | MANIFEST_KEY_PASSWORD | No | -- | Password to decrypt the keyfile | | COSMOS_MNEMONIC | No | -- | BIP-39 mnemonic (fallback when no keyfile exists) | | MANIFEST_FAUCET_URL | No | -- | Faucet URL (enables request_faucet tool on chain server) | | MANIFEST_CONVERTER_ADDRESS | Required for cosmwasm server | -- | CosmWasm converter contract address | | MANIFEST_FRED_COMPATIBILITY | No (fred and agent servers) | v0.13 | Fred protocol: v0.13, pr240, or a JSON provider API URL map (e.g. {"https://provider.example":"pr240"}); unlisted providers use v0.13. An explicit server constructor fredCompatibility option takes precedence | | MANIFEST_FRED_FETCH_GUARDED | No (fred server) | 1 (default ON) | SSRF guard for provider/Fred HTTP. Accepts 1/true/yes/on and 0/false/no/off (case-insensitive) | | MANIFEST_AGENT_FETCH_GUARDED | No (agent server) | 1 (default ON) | SSRF guard for agent-core provider HTTP. Same parser as MANIFEST_FRED_FETCH_GUARDED | | MANIFEST_AGENT_DATA_DIR | No (agent server) | -- | Directory for persisted deploy manifests (chmoded to 0o700); when unset, persistence is skipped | | MANIFEST_CHAIN_DATA_FILE | No (agent server) | -- | Path to a chain-registry JSON ({ feeTokens: [...] }) for denom humanization (umfx → MFX) | | MANIFEST_AGENT_ELICIT_TIMEOUT_MS | No (agent server) | 600000 (10 min) | Per-elicitInput timeout in milliseconds | | LOG_LEVEL | No | warn | Log level: debug, info, warn, error, or silent |

Set COSMOS_RPC_URL + COSMOS_GAS_PRICE for full access (queries + transactions). Set COSMOS_REST_URL alone for query-only mode (LCD/REST). When both are set, COSMOS_REST_URL is preferred for queries.

COSMOS_CHAIN_ID and at least one endpoint URL are only required when starting an MCP server, not for keygen or import.

Server logs use stderr; stdout carries MCP messages. The optional .env in the working directory is loaded with dotenv's parser and non-overriding population: existing process environment values take precedence. The CLI pins this parser's version and bypasses dotenv's logging wrapper, so DOTENV_CONFIG_DEBUG and DOTENV_CONFIG_QUIET cannot enable stdout diagnostics. Dotenv control variables are treated as ordinary environment data; DOTENV_KEY does not activate .env.vault loading. Use a plain .env or inject the process environment directly.

Chain server tools (6, +1 optional)

| Tool | Description | |------|-------------| | get_account_info | Get account address for the configured key | | cosmos_query | Execute any Cosmos SDK query command | | cosmos_tx | Execute any Cosmos SDK transaction | | cosmos_estimate_fee | Estimate gas + fee for a transaction without broadcasting | | list_modules | List all available query and transaction modules | | list_module_subcommands | List available subcommands for a specific module | | request_faucet | Request tokens from a faucet (registered only when MANIFEST_FAUCET_URL is set) |

Lease server tools (8)

| Tool | Description | |------|-------------| | credit_balance | Query on-chain credit balance (defaults to the caller; accepts tenant) | | fund_credit | Send tokens to a billing credit account (defaults to the sender; accepts tenant) | | leases_by_tenant | List leases by state (defaults to the caller; accepts tenant) | | close_lease | Close a lease on-chain | | set_item_custom_domain | Claim or release a custom domain on a lease item | | lease_by_custom_domain | Look up the lease that owns a custom domain | | get_skus | List available SKUs | | get_providers | List available providers |

Fred server tools (12)

| Tool | Description | |------|-------------| | browse_catalog | Browse available providers and service tiers with health checks | | check_deployment_readiness | Pre-flight checks (wallet balances, credit account, SKU availability) before deploy_app | | build_manifest_preview | Preview the manifest (and its meta_hash_hex) that deploy_app would submit | | deploy_app | Deploy a new application (create lease + deploy container, optional custom domain) | | wait_for_app_ready | Poll provider until a deployed app reports ready | | app_status | Get detailed status for a deployed app by lease UUID | | get_logs | Get logs for a deployed app by lease UUID | | restart_app | Restart a deployed app via the provider | | update_app | Update a deployed app with a new manifest | | restore_app | Recover a CLOSED or credit-exhausted lease's retained volumes onto a fresh lease | | app_diagnostics | Get provision diagnostics for a deployed app | | app_releases | Get release/version history for a deployed app (20 most recent; the stored manifest is omitted, its size reported as manifest_bytes) |

The Fred server also exposes 3 MCP resources (manifest://leases/active, manifest://leases/recent, manifest://providers) and 3 prompts (deploy-containerized-app, diagnose-failing-app, shutdown-all-leases).

CosmWasm server tools (2)

| Tool | Description | |------|-------------| | get_mfx_to_pwr_rate | Get the current MFX-to-PWR conversion rate and preview amounts | | convert_mfx_to_pwr | Convert MFX tokens to PWR via the on-chain converter contract |

Agent server tools (5)

Orchestrated wrappers over @manifest-network/manifest-agent-core. The three broadcasting tools translate the orchestrator's typed callbacks into MCP elicitation/create requests, so they require an elicitation-capable host (Claude Code >= 2.1.76); the two read-only tools run on any host. All five emit notifications/progress.

| Tool | Host requirement | Description | |------|------------------|-------------| | deploy_app_orchestrated | Elicitation | Plan-confirm-deploy flow with typed progress and partial-success recovery options | | manage_domain_orchestrated | Elicitation | Claim, verify or release a custom domain on a lease | | close_lease_orchestrated | Elicitation | Confirm, then cancel PENDING, close ACTIVE, or observe an already terminal lease without broadcasting; verify terminal state on-chain | | lookup_custom_domain_orchestrated | Any | Read-only reverse lookup: which lease owns a custom domain | | troubleshoot_deployment_orchestrated | Any | Read-only diagnosis of a failing deployment |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@manifest-network/manifest-mcp-node

Setup

Wallet setup

Option A -- Generate a new keyfile (recommended)

Option B -- Import an existing mnemonic

Option C -- Mnemonic via environment variable (fallback)

Wallet resolution order

CLI reference

Recovering the mnemonic

MCP client integration

Claude Desktop

Query-only mode (REST/LCD)

Environment variables

Chain server tools (6, +1 optional)

Lease server tools (8)

Fred server tools (12)

CosmWasm server tools (2)

Agent server tools (5)

See also

License