# AI 에이전트 (MCP)

> neurochain-mcp Model Context Protocol 서버로 AI 어시스턴트를 NeuroChain에 연결하기 — Claude Code와 Claude Desktop 설정, 모든 읽기·쓰기 도구, 세션 키 서명, 지출 한도, Sentinel 보류.

Source: https://docs.nro.world/ko/build/mcp

`neurochain-mcp`는 [Model Context Protocol](https://modelcontextprotocol.io) 서버입니다. AI 어시스턴트 — Claude Code, Claude Desktop 또는 모든 MCP 클라이언트 — 가 체인을 읽고, 여러분이 정한 한도 안에서 체인에 작업을 수행할 수 있게 해 줍니다.

```
AI 어시스턴트 ⇄ (stdio 기반 MCP) ⇄ neurochain-mcp ⇄ (HTTP) ⇄ gateway :3000 ⇄ 노드 :9933
```

서버는 저장소의 `neurochain-mcp/`에 있는 순수 Node.js입니다(빌드 단계 없음). gateway의 REST API와만 통신합니다.

## 안전을 유지하는 방법

- 쓰기 작업은 지갑의 마스터 키가 아니라 **세션 키**로 서명됩니다. 이 키는 마스터 키가 **범위**, **지출 한도**, **만료**를 지정해 부여하며, 모든 검증자가 합의 과정에서 이를 강제합니다 — [계정 추상화 → 세션 키](/ko/ai/account-abstraction#session-keys)를 참고하세요.
- 세션 키로는 Sentinel 신뢰 목록을 관리하거나 보류된 송금을 확인할 수 없습니다. [Sentinel](/ko/ai/sentinel)이 위험한 송금을 보류하면, 그것을 통과시킬 수 있는 사람은 여러분뿐입니다.
- 스테이킹, 위임, 거버넌스 투표는 에이전트에게 노출되지 않습니다.
- 세션 키가 없으면 서버는 **읽기 전용**으로 동작합니다.

## 설정

### 1. 설치

```bash
cd neurochain-mcp
npm install
```

### 2. 세션 키와 설정 파일 만들기

웹 지갑에서 **Agent** 패널을 열고 세션 키를 만드세요 — 보낼 수 있는 주소(또는 `*`), 총 지출 한도, 유효한 블록 수를 선택한 뒤 — **Export config**를 클릭합니다. 다음과 같은 결과를 얻습니다.

```json
{
  "node_rpc": "http://localhost:3000",
  "account": "neuro:<15 hex>.human",
  "session_pk": "<세션 공개 키, hex>",
  "sk_seed_hex": "<세션 키 시드, hex>",
  "scope": "*"
}
```

| 필드 | 의미 |
|------|------|
| `node_rpc` | **gateway** URL(노드의 9933 포트가 아님). 지갑이 페이지 자체의 주소를 채워 넣으므로, gateway가 다른 곳에서 실행 중이면 변경하세요 |
| `account` | 에이전트가 대신 작업하는 주소 |
| `session_pk`, `sk_seed_hex` | 세션 키. 읽기 전용으로 쓰려면 둘 다 비워 두세요 |
| `scope` | 참고용일 뿐입니다 — 실제로 강제되는 것은 체인에 기록된 권한입니다 |

저장소 밖에 저장하고 비공개로 유지하세요. `sk_seed_hex`는 비밀 값입니다.

### 3. 서버 등록

**Claude Code:**

```bash
claude mcp add neurochain \
  --env NEUROCHAIN_MCP_CONFIG=/absolute/path/to/neurochain-mcp.config.json \
  -- node /absolute/path/to/neurochain-mcp/src/index.js
```

**Claude Desktop**(`claude_desktop_config.json`) 또는 프로젝트의 `.mcp.json`:

```json
{
  "mcpServers": {
    "neurochain": {
      "command": "node",
      "args": ["/absolute/path/to/neurochain-mcp/src/index.js"],
      "env": { "NEUROCHAIN_MCP_CONFIG": "/absolute/path/to/neurochain-mcp.config.json" }
    }
  }
}
```

절대 경로를 사용하세요. 클라이언트는 자신의 작업 디렉터리에서 서버를 시작합니다.

## 도구

### 읽기

| 도구 | 매개변수 | 반환 |
|------|----------|------|
| `nc_get_account` | `address`(기본값: 설정된 계정) | 잔액, nonce, 트랜잭션 수 |
| `nc_get_txs` | `address`, `limit`(1–200) | 트랜잭션 기록 |
| `nc_gas_estimate` | — | 기본 수수료와 수수료 추정치 |
| `nc_list_proposals` | `status`, `limit`(1–100), `offset` | 집계가 포함된 거버넌스 제안 |
| `nc_list_validators` | — | 스테이크와 메트릭이 포함된 검증자 |
| `nc_get_contract` | `address`(`.app`) | 소유자, 코드 해시, 보안 점수 |
| `nc_analyze_contract` | `bytecode_hex` | VMGuardian 분석 — 위험도, 위반 사항 |
| `nc_get_session_grants` | `address` | 한도와 지출액이 포함된 계정의 세션 키 |
| `nc_get_held` | `address` | Sentinel이 보류한 송금 |

### 쓰기 (세션 키 필요)

| 도구 | 매개변수 | 비고 |
|------|----------|------|
| `nc_transfer` | `to`, `amount_nro`(NRO, 소수 허용) | Sentinel이 보류하면, 도구가 자동으로 해제되는지 아니면 여러분의 확인이 필요한지 알려 줍니다 |
| `nc_call_contract` | `to`(`.app`), `function`, `args`, `value`(uNRO, 기본값 0) | |
| `nc_deploy` | `bytecode_hex`, `name`, `description`, `template`, `init_args` | 다른 배포와 마찬가지로 VMGuardian 게이트를 거칩니다 |

각 쓰기 작업은 다음 nonce를 읽고, 세션 키로 서명한 뒤 `POST /api/v1/transactions`로 전송합니다. 노드는 모든 검증자에서 권한을 확인합니다. 예를 들어 한도를 넘는 송금은 다음과 같이 반환됩니다.

```
Error: POST /api/v1/transactions failed: HTTP 401 — session spend cap exceeded
```

## 테스트 결과

로컬 테스트 네트워크에서: 읽기 도구는 실시간 데이터를 반환했고, 한도가 5 NRO인 세션 키로 보낸 1 NRO `nc_transfer`는 확정되어 권한에 `spent: 1000000`으로 기록되었습니다. 이어서 보낸 10 NRO 송금은 위 오류와 함께 거부되었습니다. 세션 키가 설정되지 않은 상태에서는 쓰기 도구가 서명하지 않고 거부합니다.

## 철회

지갑의 Agent 패널에서 키를 철회하거나, 마스터 키로 서명한 `POST /api/v1/session/revoke`를 사용하세요. 다음 블록부터는 이 키로 서명된 모든 것이 거부됩니다.