@invariance/mcp

AI 코딩 에이전트를 Invariance 관측성 플랫폼에 연결하는 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Cursor, Claude Code와 같은 도구들이 실행, 노드, 모니터, 신호, 발견 사항, 리뷰 등에 직접 액세스할 수 있도록 합니다.

MCP는 AI 어시스턴트가 외부 도구와 데이터 소스를 사용할 수 있게 하는 개방형 프로토콜입니다. 이 서버는 Invariance를 위해 이를 구현하므로, AI 어시스턴트가 대화창을 벗어나지 않고도 관측성 데이터를 쿼리하고, 문제를 조사하며, 에이전트 동작을 분석할 수 있습니다.

설치

npm install -g @invariance/mcp

또는 npx를 사용하여 직접 실행하세요(MCP 클라이언트 설정에 권장):

npx @invariance/mcp

Related MCP server: Claude Code Starter Kit MCP

설정

환경 변수

app.invariance.ai/settings/api-keys에서 API 키를 받으세요.

Claude Desktop

Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json, macOS 기준)에 추가하세요:

{
  "mcpServers": {
    "invariance": {
      "command": "npx",
      "args": ["-y", "@invariance/mcp"],
      "env": {
        "INVARIANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Claude Code 설정(.claude/settings.json 또는 ~/.claude/settings.json)에 추가하세요:

{
  "mcpServers": {
    "invariance": {
      "command": "npx",
      "args": ["-y", "@invariance/mcp"],
      "env": {
        "INVARIANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Cursor MCP 설정(.cursor/mcp.json)에 추가하세요:

{
  "mcpServers": {
    "invariance": {
      "command": "npx",
      "args": ["-y", "@invariance/mcp"],
      "env": {
        "INVARIANCE_API_KEY": "your-api-key"
      }
    }
  }
}

사용 가능한 도구

이 서버는 전체 Invariance API를 포괄하는 37개의 도구를 제공합니다. 이름은 invariance_<리소스>_<작업> 형식을 따릅니다.

실행(Runs) (invariance_run_*) start, get, list, finish, fail, verify, metrics

노드(Nodes) (invariance_node_*) write, list

모니터(Monitors) (invariance_monitor_*) create, list, get, update, pause, resume, evaluate, executions, findings

신호(Signals) (invariance_signal_*) emit, list, get, acknowledge, resolve

발견 사항(Findings) (invariance_finding_*) list, get, update

리뷰(Reviews) (invariance_review_*) list, get, claim, unclaim, resolve

에이전트(Agents) (invariance_agent_*) me, set_key

인사이트(Insights) invariance_narrative_get (LLM으로 요약된 실행 요약), invariance_ask (지식 베이스 + 실행에 대한 턴 기반 Q&A), invariance_kb_pages_list, invariance_kb_page_get

복잡한 객체 인수(모니터 본문, 신호 데이터, 노드 입력/출력, 실행 메타데이터)의 경우, 도구는 JSON으로 인코딩된 문자열을 허용하며, 서버는 이를 API로 전달하기 전에 파싱합니다.

레거시 도구 별칭

이전 버전의 6개 도구 이름은 기존 클라이언트 설정이 계속 작동하도록 별칭으로 유지됩니다: invariance_create_run, invariance_get_run, invariance_list_runs, invariance_write_node, invariance_list_nodes, invariance_verify_run.

HTTP 전송

stdio 대신 Streamable HTTP를 통해 서버를 실행하려면:

INVARIANCE_API_KEY=your-api-key INVARIANCE_MCP_TRANSPORT=http INVARIANCE_MCP_PORT=3000 npx @invariance/mcp

서버는 http://127.0.0.1:3000/mcp에서 Streamable HTTP 엔드포인트를, http://127.0.0.1:3000/health에서 상태 확인을 제공합니다.

HTTP 전송을 지원하는 MCP 클라이언트는 하위 프로세스를 생성하는 대신 /mcp 엔드포인트 URL을 사용하여 연결할 수 있습니다.

문제 해결

"INVARIANCE_API_KEY environment variable is required"

MCP 클라이언트 설정에서 INVARIANCE_API_KEY 환경 변수를 설정했는지 확인하세요. 위의 설정 가이드를 참조하세요.

MCP 클라이언트에 서버가 나타나지 않음

1. 클라이언트의 설정 파일 경로가 올바른지 확인하세요.

2. 설정을 편집한 후 클라이언트를 다시 시작하세요.

3. 터미널에서 npx @invariance/mcp가 오류 없이 실행되는지 확인하세요.

인증 오류

app.invariance.ai/settings/api-keys에서 API 키가 유효한지 확인하세요.

연결 타임아웃

사용자 지정 INVARIANCE_BASE_URL을 사용하는 경우, 해당 URL에 연결할 수 있는지 확인하세요.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT