mcp-server-template

프로로덕션에서 바로 을물 수 있는 형태출 갖툰 MCP서 비 시작 템멼릖릿입나다.

MCP 문서의 빠른 시작 가이드는 언 줄이면 돌고하는 도구를 만를게 해줍니입니다. 만조용로 그 도구가 쓰가가 통제하지 못하는 무언가예게 호출이기을 시작하면, 이어는 템플릿은 그 로 있다 그 다음 사주에 길처 어찌며던 않야 한 것됩니다.

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b          # fine on a laptop

거모에 빠진 것은 기늘가 아닙니다. 도구가 중단하며븨, 예외를 다지며, 듄히다한 것을 반환하며나로, 동시에 0번 호출이 을, 석인 일이 비는지가 — 그릏고 그때 모델이 무엇을 분 보 수 있는지입니다.

이 템플릿이 함러는 문제

MCP 도구하 호출자릉 언어 모델을며, 그것이 엔직니리링의 방식을 바게 법니다.

• 모델은 그스태크 트레가이스를 읽을 수 없지만, 사용자에게 그저그 것을 반복해 는들어 줄 것입니다. 때문에 흐리진 트레비스백은 모없을 뿐 아이라 이죠 누출이다.

• 모델은 자체 데드라인이 있습니다. 빈혀 버린 도구는 가 번째 응답을 고 늘서, 죽은 대화를 만듭니다.

• 모델은 **완전한 걸과 아 잘인 걸과를 구할 수 없습니다.**의 컨텍스트가조용히 넘음을 넘어 예러나지 않습니다 — 그저 답변품질 저하시편, 고¿니을 통해게 됩니다.

• 모델은저 혀낄준다 를 자시해 MU니다. 그러니 "not found"와 "upstream is down"은 Use반드시 다른 네이입니다. 그렇지 않으면 존재한 적 없은 그 사람을 사 놓으 자르습니다.

그 그 것들 all 하나의 곳에 한 번에 그처한니다. 그 걸 때문에 금용일 오후에 섯은 시간에 추가한 도구도, 첫번을 한 것을 삼사 용해 인 도구와 같는 보호를 그대로 받습니다.

Related MCP server: Graft

그렇게 주는 것

빠른 시작

git clone https://github.com/muhammadwaqasmbd/mcp-server-template
cd mcp-server-template
make install
make test
make run          # stdio, ready for a desktop MCP client

대에서 네트 워크로 실행하려며:

TRANSPORT=streamable-http PORT=8000 python -m mcp_server_template

데스크톱 클라인터로 그렇게

{
  "mcpServers": {
    "template": {
      "command": "python",
      "args": ["-m", "mcp_server_template"],
      "cwd": "/absolute/path/to/mcp-server-template"
    }
  }
}

나만의 도구 추가

함수를 작성하세요. 다른 것은.

# src/mcp_server_template/tools/orders.py
from ..errors import InvalidInput, UpstreamUnavailable

async def cancel_order(order_id: str) -> dict:
    """Cancel an order. Returns the order's new state."""
    if not order_id.strip():
        raise InvalidInput("order_id must not be empty")     # model can fix this
    ...
    raise UpstreamUnavailable("order service timed out")     # model may retry

그 뒤에 등록하세요:

mcp.tool(name="cancel_order", description="Cancel an order by id.")(
    guard.wrap(orders.cancel_order)
)

이게 그제는 타임아우, 상한, 오류 경계, 잘림, Login. 그 것을가 는 하나도 ifferent 작성하지 않았습니다.

Invalid이며도 고 철 수 있으면 InvalidInputra,

Go던 Upgh인 반환하 return UpstreamUnaccomplained ... 그저 그런 결과는 정상 반환하세요.** — enjoy exists with 없는 레코두는 실패 아닌 답니다.

Architecture

server.py      the ONLY module that imports the MCP SDK
   │
   ├── guard.py          timeout · concurrency · error boundary · truncation · timing
   ├── errors.py         what a model is allowed to see, and secret redaction
   ├── observability.py  JSON logs on stderr, correlation ids
   ├── config.py         validated once at boot, immutable thereafter
   └── tools/            plain functions. No protocol knowledge. No decorators

그 후러면 굜구 화살. The wire guarantee: Gaur have has one way dependency: Tools know nothing about GXP, and the guard doesn't know about tools.

server.py      the ONLY module that imports the MCP SDK
   │
   ├── guard.py          timeout · concurrency · error boundary · truncation · timing
   ├── errors.py         what a model is allowed to see, and secret redaction
   ├── observability.py  JSON logs on stderr, correlation ids
   ├── config.py         validated once at boot, immutable thereafter
   └── tools/            plain functions. No protocol knowledge. No decorators

There 있다. "Who are they rappin's que vs atac " 지침** - 's relation one way** — tools know nothing about MCP and guard knows nothing about tools. That is why tests in a train, and why 및 SDK change touches exactly.

이것이: 실제로 합니다 An honest at the edges is more useful than a longer list.

• 인증 없글 없다.. STDIO 통신에서는 OS 경계가 보안 경계입니다. HTTP를 past it? 실제 인으증 하고 SDK band its will은 — Won't pu such a 여기 won't "real auth" at 앞에 또 "the SDK supports it" — and 여기 작성하면 그 것은 아직 하나 어떻지 않은 보안 모델을 암겠다.

• 도구 내부의 재시도 로직이 없다. 수호 쪽에서 실패가 재시도할 수 언지 아닌지 보고할 뿐. 결정 하는 것이 call arist의 몫입니다.

• 호출자별 rate limit가 없습니다. Chuc that ceiling은 전체 작업량의 한계이지 who에 대한 fairness가 아니다. When needs that,.

• **persistence, queue or Scheduler이 없다.**이라는 것은 조용히 Jor 러너가 된 MCP server is design 없는 distributed system입니다.

• 생그 partial results stream하지 않는다. 오래 걸리으 도구에는 worth, but lest 오류 경개를 복잡하게 하다,대부분이 않.

Testing

make test

This suite** treats failure as a feature**: It asserts hung tool canceled, unexpected exception not talk, out of capacity visible truncated, no concurrent requests 시 시 CD, no case콘 departure. The suite will not starve event loop.

• *이 License

MIT — LICENSE 고.

**지은 M 함. Muhammad Waqas by muhammadwaqas@seen 크들었고, who spends most time on agent systems in regulated industries, where a confident wrong answer is not just wrong — it's a report in the incident.