본문으로 건너뛰기
번역된 페이지

이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.

AI 에이전트

StackQL은 사람이 클라우드 및 SaaS 서비스를 쿼리하고, 프로비저닝하고, 운영할 때 사용하는 것과 동일한 SQL 인터페이스를 AI 에이전트에 제공합니다. 에이전트는 프로바이더가 노출하는 항목을 탐색하고, 쿼리를 실행하기 전에 검증하고, SELECT 문으로 실시간 상태를 읽고, INSERT, UPDATE, DELETE 문으로 상태를 변경합니다. 상태 파일이나 클라우드별 SDK는 필요하지 않습니다.

에이전트 연결 방식​

  • stdio를 통한 MCP는 Claude Desktop, Cursor, Continue 같은 편집기 및 데스크톱 클라이언트용입니다. 클라이언트가 stackql mcp --mcp.server.type=stdio 명령을 직접 실행합니다. MCP 서버를 참조하세요.
  • HTTP를 통한 MCP는 장기 실행 중인 stackql mcp 또는 stackql srv 프로세스에 연결하는 독립 실행형 에이전트와 자동화용이며, Bearer 토큰 인증과 선택적 TLS를 지원합니다.
  • 임베디드 MCP는 컴파일된 애플리케이션용입니다. 서버는 Go, Rust, Swift, Kotlin, .NET, Gleam 애플리케이션의 프로세스 내에서 실행됩니다. 임베디드 MCP를 참조하세요.
  • PostgreSQL 와이어 프로토콜은 stackql srv 명령을 통해 제공되며, 이미 Postgres 프로토콜을 사용하는 에이전트 프레임워크, 노트북, BI 도구용입니다.

Claude Desktop을 사용한 빠른 시작​

Anthropic Connector Directory(권장) 또는 다운로드 가능한 MCP Bundle에서 설치하거나, claude_desktop_config.json 파일에 서버를 직접 등록합니다.

{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": ["mcp", "--mcp.server.type=stdio", "--tls.allowInsecure"],
"env": {
"AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key"
}
}
}
}

사용할 프로바이더의 자격 증명만 포함하세요. 번들 다운로드와 자격 증명 파일 사용을 포함한 전체 지침은 Claude Desktop에서 StackQL 사용에 있습니다.

에이전트가 할 수 있는 작업​

MCP 서버는 작고 형식이 지정된 도구 집합을 노출합니다. 각 도구는 모델용으로 렌더링된 뷰와 프로그래밍 방식 클라이언트용 구조화된 페이로드를 반환합니다.

  • 탐색: list_providers, list_services, list_resources, list_methods, describe_method 도구는 프로바이더 계층 구조를 순회하고 각 작업의 입력과 출력 필드를 반환합니다. 따라서 쿼리를 작성하기 전에 필요한 WHERE 매개 변수를 알 수 있습니다.
  • 검증 및 읽기: validate_select_query 도구는 SELECT 문을 실행하지 않고 구문 분석하고 실행 계획을 수립합니다. run_select_query 도구는 이 문을 실행합니다.
  • 변경: run_mutation_query 도구는 INSERT, UPDATE, REPLACE, DELETE 문을 실행하고, run_lifecycle_operation 도구는 EXEC 수명 주기 작업을 실행합니다. 두 도구 모두 아래의 서버 모드에 의해 게이트 제어됩니다.
  • 유지 관리: server_info, list_registry, pull_provider, reload_credentials.

도구별 입력, 게이트 제어 동작 및 예제 프롬프트를 포함한 전체 참조는 MCP 도구에 있습니다.

가드레일​

서버 모드는 세션 전체의 안전 계약을 설정합니다.

모드SELECT / 메타데이터INSERT / UPDATE / REPLACEDELETE / EXEC
read_only허용거부거부
safe(기본값)허용승인 필요승인 필요
delete_safe허용허용승인 필요
full_access허용허용허용

"승인 필요"는 MCP 엘리시테이션(elicitation)을 사용합니다. 이를 지원하는 클라이언트(Claude Desktop, Cursor, Continue)는 사용자에게 도구 이름, 쿼리 클래스, SQL을 표시하고, 어떤 작업이든 실행하기 전에 결정을 기다립니다. 이 기능을 알리지 않는 클라이언트는 거부됩니다. 모든 도구 호출은 감사 로그에 기록되고, HTTP 리스너에는 Bearer 토큰이 필요하며, 자격 증명은 환경 또는 dotenv 파일에서 로드되고 시크릿 값은 클라이언트에 반환되지 않습니다. 자세한 내용은 서버 모드, HTTP 클라이언트 인증, 감사 로그를 참조하세요.

다음 단계​

  • MCP 서버: 배포 모드, 구성, 서버 모드, 감사 로그 및 플래그.
  • MCP 도구: 입력, 게이트 제어 및 예제 프롬프트를 포함한 전체 도구 참조.
  • 임베디드 MCP: 자체 Go, Rust, Swift, Kotlin, .NET 또는 Gleam 애플리케이션 내에서 서버 실행.
  • Query Library: 일반적인 클라우드 운영 질문에 바로 실행할 수 있는 SQL(프로바이더별).
  • AI 참조: 에이전트와 에이전트를 만드는 사람을 위해 작성된 개념, 사용 방법, 비교 및 문제 해결 문서.