# QoreChain MCP

An [MCP](https://modelcontextprotocol.io) server and a CLI that give AI agents and developer tools read access to [QoreChain](https://www.qorechain.io): blocks, transactions, accounts, validators, staking tiers, the status of the hybrid secp256k1 + ML-DSA-87 (FIPS 204) signature, contract reads, simulation and fee estimates, and unsigned transfers for the user's own wallet to sign.

The server never signs, never holds keys and never broadcasts.

| Package | What it is |
|---|---|
| [`@qorechain/mcp`](packages/server) | MCP server: stdio (`npx -y @qorechain/mcp`) and Streamable HTTP (`qorechain-mcp serve`), plus Fetch API and AWS Lambda handlers for self-hosting |
| [`@qorechain/qore-cli`](packages/cli) | `qore` command line with `--json` output identical to the MCP tool output |
| [`qorechain-mcp` (Python)](python) | the same server for Python stacks (`uvx qorechain-mcp`) |
| [Container image](docs/self-hosting.md#container) | `ghcr.io/qorechain/qorechain-mcp`, runs `qorechain-mcp serve` |

## Quickstart

Add the server to any MCP client that starts local servers:

```json
{
  "mcpServers": {
    "qorechain": { "command": "npx", "args": ["-y", "@qorechain/mcp"] }
  }
}
```

Then ask your agent, for example: "Is transaction F642F59F...2152 on QoreChain testnet hybrid-signed, and does the ML-DSA-87 layer verify?" Step by step: [docs/quickstart.md](docs/quickstart.md).

From a terminal:

```bash
npx -y @qorechain/qore-cli pq status F642F59F2A2FEDA2B3A61A3CF49F8B5F792D65985027997004FEBB22A6F42152
npx -y @qorechain/qore-cli account qor1... --network mainnet --json
```

## Tools

Every tool takes an optional `network`: `testnet` (chain `qorechain-diana`, the default) or `mainnet` (chain `qorechain-vladi`). Full schemas: [docs/tools.md](docs/tools.md).

| Tool | What it returns |
|---|---|
| `get_chain_info` | chain ids, latest block, minimum gas price, sign-bytes version, protocol features, pending upgrade, active EVM precompiles |
| `get_block` | one block (or the latest): hash, time, proposer, transaction hashes |
| `get_transaction` | a transaction by native or EVM hash: status, fee, messages, signers, signature tier |
| `get_address_info` | balances, account state, staked amount, both address forms (`qor1...` and `0x...`) |
| `get_pq_status` | for an address: registered ML-DSA-87 key, key type, proof of possession, EVM window; for a transaction: exactly one hybrid layer present, and whether it verifies against the signer's registered key |
| `get_validators` | validators by stake, voting power share, commission |
| `get_staking_tiers` | lock terms and bonuses, bonus pool, one holder's locks |
| `search` | detects a height, hash, address or validator and reads it |
| `read_contract` | EVM `eth_call` only, with optional ABI encoding and decoding |
| `estimate_fee` | simulated gas, suggested gas limit and fee (including the ML-DSA-87 layer) |
| `simulate_tx` | gas, balance changes and decoded refusals for an encoded transaction |
| `prepare_transfer` | an unsigned SignDoc for a transfer, with checks and warnings |
| `get_token_holders` | not available: needs an indexer the public endpoints do not provide |
| `request_faucet` | not available here: testnet QOR comes from the dashboard faucet (sign-in required) |

The EVM precompiles `0x...0A01` (ML-DSA-87 verify) and `0x...0A02` (key status) are active on testnet only.

Errors carry a stable code: `NOT_FOUND`, `INVALID_INPUT`, `UPSTREAM_UNAVAILABLE`, `NOT_AVAILABLE_ON_CHAIN`, `RATE_LIMITED`, `UNAUTHORIZED`, `INTERNAL_ERROR`.

## Endpoints used

| | Mainnet | Testnet |
|---|---|---|
| REST | `https://api.qore.host` | `https://api-testnet.qore.host` |
| RPC | `https://rpc.qore.host` | `https://rpc-testnet.qore.host` |
| EVM JSON-RPC | `https://evm.qore.host` (chain id 9801) | `https://evm-testnet.qore.host` (chain id 9800) |
| Explorer | `https://explore.qore.network` | same, testnet selected |

## Documentation

- [Quickstart](docs/quickstart.md): an MCP client connected in under 10 minutes
- [Tools reference](docs/tools.md), generated from the server's schemas ([spec/tools.json](spec/tools.json))
- [Self-hosting](docs/self-hosting.md): HTTP, API keys, rate limits, reverse proxy, container, Lambda
- [Security](docs/security.md): what the server never does
- [Agent skills](skills): build on QoreChain, sign and send with QoreSign, integrate QoreX
- [Examples](examples) and [registry manifests](registry)

## Development

```bash
pnpm install
pnpm build && pnpm lint && pnpm typecheck && pnpm test
QORE_LIVE_TEST=1 pnpm --filter @qorechain/mcp-core test   # against the public endpoints
node scripts/record-fixtures.mjs                           # re-record test fixtures
node scripts/gen-tools-spec.mjs                            # regenerate spec/tools.json and docs/tools.md
```

See [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).

## License

[Apache-2.0](LICENSE). Copyright 2026 QoreChain Association.