**Model Context Protocol (MCP)**를 사용하는 LLM 에이전트 하네스의 최소 데모입니다.
이 저장소는 에이전트가 다음을 수행할 수 있는 방법을 보여주는 작은 Node.js/TypeScript 및 Python 예제를 포함합니다:
MCP 서버에서 도구를 발견하고;
해당 도구를 LLM에 노출하며;
모델이 도구 호출을 요청하도록 하고;
MCP를 통해 해당 호출을 실행하며;
도구 결과를 모델에 반환하고;
모델이 최종 응답을 생성할 때까지 루프를 계속합니다.
중요: 이는 데모 코드일 뿐입니다. 프로덕션 코드가 아니며 안전하고 강화된 완전한 에이전트 프레임워크로 취급되어서는 안 됩니다.
이 저장소의 목적은 MCP 기반 에이전트 하네스의 메커니즘을 쉽게 검사할 수 있도록 하는 것입니다.
높은 수준에서:
User
|
v
LLM
|
| tool request
v
Agent Harness
|
v
MCP Client
|
v
MCP Server
|
v
Tool Implementation
|
v
Tool Result
|
+------------------> LLM책임은 의도적으로 분리되어 있습니다:
LLM - decides what it thinks should happen
Harness - manages the agent loop and conversation state
MCP - standardises tool discovery and invocation
Tools - perform the actual deterministic operationsMCP는 어떤 도구를 호출할지 결정하지 않습니다.
도구 선택은 주변 애플리케이션이 명시적으로 제한하거나 재정의하지 않는 한 모델의 결정으로 남습니다.
Related MCP server: MCP Server Scaffold
많은 에이전트 프레임워크 용어가 실제로 일어나는 일을 모호하게 만들 수 있습니다.
필수 하네스 루프는 다음과 같습니다:
call model
|
v
did it request a tool?
|
/ \
no yes
| |
answer execute tool
|
v
return result
|
+----> call model again이 저장소는 그 메커니즘을 큰 에이전트 프레임워크 뒤에 숨기지 않고 보이게 유지합니다.
일반적인 레이아웃은 다음과 같습니다:
.
├── node/
│ ├── package.json
│ └── src/
│ ├── agent.ts
│ └── server.ts
│
└── python/
├── agent.py
└── server.py정확한 디렉토리 이름은 아키텍처에 영향을 주지 않고 변경할 수 있습니다.
데모 서버는 의도적으로 간단한 세 가지 가상 도구를 노출합니다:
get_github_activity
get_site_content
contact_scott이는 다음을 보여주기 위한 예시일 뿐입니다:
도구 발견;
도구 스키마;
도구 설명;
인수;
실행;
결과 처리.
실제 백엔드를 나타내기 위한 것이 아닙니다.
Node.js 20+
OpenAI API 키
의존성 설치:
npm installAPI 키 설정:
export OPENAI_API_KEY="sk-..."에이전트 실행:
npm startMCP 서버는 stdio 전송을 통해 에이전트에 의해 자동으로 실행됩니다.
서버를 별도로 실행할 필요가 없습니다.
예제 출력:
MCP tools: [
'get_github_activity',
'get_site_content',
'contact_scott'
]
MODEL REQUESTED TOOL: get_github_activity
ARGUMENTS: {}
MCP RESULT:
...
FINAL ANSWER
------------
Scott has recently been working on...Python 3.10+
OpenAI API 키
가상 환경 생성:
python3 -m venv .venv
source .venv/bin/activate패키징 도구 업그레이드:
python3 -m pip install --upgrade pip setuptools wheel의존성 설치:
pip install "mcp>=2,<3" openaiAPI 키 설정:
export OPENAI_API_KEY="sk-..."실행:
python3 agent.pyPython 버전은 대화형 CLI 챗봇으로 실행됩니다:
MCP tools: ['get_github_activity', 'get_site_content', 'contact_scott']
Chat started.
Type /quit to exit.
You> hello
Assistant> Hello! How can I help?
You> What has Scott been working on?
[tool] get_github_activity({})
[result] ...
Assistant> Scott has recently been working on...Python 클라이언트는 턴 사이에 대화 기록을 유지하고 일반 응답을 터미널로 스트리밍합니다.
이 예제들은 stdio를 통한 MCP를 사용합니다.
에이전트는 MCP 서버를 자식 프로세스로 실행합니다:
agent
|
+---- stdin/stdout ---- MCP server이는 로컬 실험에 편리한 이유는 다음과 같습니다:
별도의 서버 데몬이 없음;
HTTP 엔드포인트가 없음;
포트 구성이 없음;
추가 인증 계층이 없음.
한 가지 중요한 결과는 MCP stdio 서버가 stdout에 임의의 디버깅 출력을 작성해서는 안 된다는 것입니다.
stdout은 MCP 프로토콜에 속합니다.
대신 진단에는 stderr를 사용하세요.
예를 들어:
print("debug information", file=sys.stderr)또는 TypeScript에서:
console.error("debug information");필수 하네스 로직은 다음과 같습니다:
while True:
response = await model(...)
calls = find_tool_calls(response)
if not calls:
return
for call in calls:
result = await mcp.call_tool(
call.name,
call.arguments,
)
add_result_to_context(result)실제 하네스는 추가로 다음을 구현할 수 있습니다:
permissions
timeouts
tool allowlists
human approval
rate limits
cost limits
logging
tracing
context pruning
retry policies
authentication
authorization
sandboxing
validation
auditing
error recovery이 데모는 의도적으로 그 중 거의 수행하지 않습니다.
하네스는 구현의 하드코딩된 목록이 필요하지 않습니다.
대신 MCP 서버에 사용 가능한 도구를 요청합니다.
개념적으로:
MCP server
|
| tools/list
v
Agent harness그런 다음 하네스는 결과를:
name
description
input schema모델에 노출합니다.
MCP 서버가 나중에 다른 도구를 추가하면 하네스는 다른 사용자 정의 디스패치 분기를 추가하지 않고도 이를 발견할 수 있습니다.
이는 MCP가 제공하는 주요 아키텍처 이점 중 하나입니다.
이 점은 중요합니다.
서버가 다음을 제공한다고 가정해 보세요:
contact_scott누군가 Scott을 고용하거나 연락하려고 할 때 사용해야 한다는 설명과 함께.
사용자가 말할 수 있습니다:
Can I hire Scott for consulting?원하는 모델 동작은:
contact_scott(...)하지만 LLM이 대신 일반적인 대화 응답을 생성할 수도 있습니다.
MCP는 그 문제를 해결하지 않습니다.
결정:
Does this natural-language request imply this tool?여전히 확률적 모델 추론입니다.
도구 설명은 라우팅 동작을 개선하지만 공식적인 보장을 생성하지는 않습니다.
작업이 결정론적으로 발생해야 하는 경우, 해당 요구 사항은 LLM 명령에만 의존하지 않고 일반 애플리케이션 로직에서 적용되어야 합니다.
모델이 도구를 요청하면 나머지 시스템은 결정론적일 수 있습니다:
model requests tool
|
v
validate arguments
|
v
check permission
|
v
execute function
|
v
return result하지만 초기 의미론적 결정은 여전히 확률적일 수 있습니다.
이 구분은 다음과 같은 결과를 초래하는 작업에 특히 중요합니다:
sending money
deleting data
changing permissions
submitting legal information
making purchases
sending messages
altering customer records프로덕션 시스템은 의미 있는 결과를 초래하는 작업 주변에 명시적인 결정론적 제어를 배치해야 합니다.
Python CLI는 스트리밍을 사용하므로 텍스트가 생성될 때 나타납니다.
스트리밍 없이:
You> explain virtual memory
<wait>
Assistant> Virtual memory is...스트리밍 사용:
You> explain virtual memory
Assistant> Virtual memory is...스트리밍은 주로 인지된 지연 시간을 개선합니다.
도구를 사용하는 턴은 여러 모델 요청이 필요할 수 있으므로 여전히 더 오래 걸릴 수 있습니다:
model request
|
v
tool call
|
v
MCP execution
|
v
tool result
|
v
second model request이 저장소는 의도적으로 최소화되었습니다.
프로덕션 에이전트 시스템에서 기대되는 안전 장치를 제공하지 않습니다.
다른 것들 중에서도 프로덕션 코드는 다음을 고려해야 합니다:
인증;
권한 부여;
비밀 관리;
적대적 도구 입력;
프롬프트 인젝션;
출력 검증;
도구 결과 검증;
스키마 적용;
리소스 제한;
네트워크 격리;
서브프로세스 보안;
결과적 작업에 대한 사용자 확인;
감사 로깅;
재시도 동작;
실패 복구;
비용 제어;
컨텍스트 증가;
모델 버전 변경;
API 버전 변경;
의존성 고정;
관찰 가능성;
테스트 및 평가;
개인정보 보호 및 데이터 보존 요구사항.
적절한 검증, 인증, 지속성, 남용 방지 및 오류 처리를 추가하지 않고 예제 MCP 서버를 신뢰할 수 없는 사용자에게 직접 노출하거나 실제 통신에 예제 contact_scott 패턴을 사용하지 마십시오.
다시 말하지만:
이 저장소는 학습 및 실험을 위한 데모 코드이며, 프로덕션 배포를 위한 것이 아닙니다.
계층을 분리하여 유지하는 것이 유용합니다:
MCP
!= LLM
MCP
!= agent
MCP
!= tool-selection logic
MCP
!= security policyMCP는 기능을 노출하고 호출하는 데 사용되는 프로토콜입니다.
하네스는 모델/도구 루프를 관리합니다.
모델은 언어 추론을 수행합니다.
기본 도구는 실제 작업을 수행합니다.
유용한 정신 모델은:
Agent System
=
Model
+
Harness
+
Tools
+
Context
+
PolicyMCP는 해당 구성 요소 중 일부 간에 표준 인터페이스를 제공합니다.
하나의 애플리케이션에 있는 세 개의 로컬 함수의 경우, 절대적으로 가능합니다.
예를 들어:
TOOLS = {
"foo": foo,
"bar": bar,
}MCP보다 더 간단할 수 있습니다.
MCP는 기능을 여러 클라이언트에서 재사용해야 할 때 더 흥미로워집니다:
MCP Server
/ | \
/ | \
/ | \
CLI agent IDE website도구 제공자는 특정 모델 호스트나 애플리케이션으로부터 독립적이 됩니다.
이것이 MCP를 도입하는 주요 아키텍처 이유입니다.
기본 CLI가 작동하면 유용한 실험은 다음과 같습니다:
run the same prompt repeatedly
change tool descriptions
change models
change system instructions
record selected tools
measure latency
measure token usage
add approval gates
add deliberately ambiguous prompts
add multiple MCP servers
introduce tool failures
introduce malformed results
limit maximum agent steps특히 유용한 테스트 중 하나는 기록하는 것입니다:
prompt
selected tool
arguments
number of model calls
latency
final response반복 실행에 걸쳐.
이를 통해 모델에서 얼마나 많은 변동이 발생하는지, 그리고 하네스에 의해 얼마나 많은 동작이 제어될 수 있는지 검사할 수 있습니다.
저장소에 적합한 라이선스를 추가하세요.
이 코드의 요점은 또 다른 대규모 에이전트 프레임워크를 제공하는 것이 아닙니다.
핵심 프로세스를 이해할 수 있을 정도로 메커니즘을 명확하게 노출하는 것입니다:
Model proposes.
Harness controls.
MCP connects.
Tools execute.더 정교한 모든 것은 그 위에 구축됩니다.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Synaptechlabs/mcp-minimal-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server