Skip to main content
Glama
deenesjakoruzh
milad13711

Exir MCP Server

by milad13711
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Exir MCP Server

MCP 호스트(Claude, ChatGPT 또는 기타 MCP 호환 에이전트)와 Exir CRM API(내부적으로 Perfex CRM) 사이에 위치하는 멀티 테넌트 Model Context Protocol 게이트웨이입니다.

                    ┌──────────────────────┐
                    │   ChatGPT / Agent     │
                    │ Claude / Other Host   │
                    └──────────┬────────────┘
                               │
                         MCP / HTTPS
                               │
                               ▼
              ┌────────────────────────────────┐
              │        Exir MCP Server          │
              │                                 │
              │ OAuth 2.1 / OIDC                │
              │ Tenant Resolver                 │
              │ Permission Engine               │
              │ Tool Registry                   │
              │ Audit Logger                    │
              │ Rate Limiter                    │
              │ Input Validation                │
              └───────────────┬─────────────────┘
                               │
                        Internal API
                               │
                               ▼
              ┌────────────────────────────────┐
              │          Exir CRM API           │
              │                                 │
              │ Customers / Leads / Sales       │
              │ Tasks / Projects / Tickets      │
              │ Invoices / Contracts / ...      │
              └───────────────┬─────────────────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │ Customer Tenant   │
                    │ Data / Database   │
                    └──────────────────┘

요청 흐름

  1. 전송 — MCP 호스트가 Bearer 액세스 토큰과 함께 POST /mcp(Streamable HTTP) 요청을 보냅니다.

  2. OAuth 2.1 / OIDC (src/auth/oidc.ts) — 토큰의 서명, 발급자, 대상 및 만료 시간이 ID 공급자의 JWKS에 대해 검증됩니다. 검증되지 않은 토큰은 이 계층 아래로 절대 도달하지 않습니다.

  3. 테넌트 리졸버 (src/tenant/tenantResolver.ts) — 테넌트 ID는 검증된 토큰의 클레임에서 읽혀 해당 테넌트의 Exir CRM 연결(기본 URL + API 키)에 매핑됩니다. 요청은 테넌트 경계를 절대 넘을 수 없습니다.

  4. 속도 제한기 (src/middleware/rateLimiter.ts) — 요청은 테넌트별로 제한되어 공유 배포에서 한 호출자가 다른 호출자를 굶기지 않습니다.

  5. 도구 레지스트리 (src/tools/) — 이 요청에 대한 MCP 서버는 등록된 모든 도구(src/mcp/server.ts)를 다음으로 래핑하여 구축됩니다:

    • 권한 엔진 (src/permissions/permissionEngine.ts) — 토큰의 OAuth 범위를 도구의 필수 범위와 대조합니다.

    • 입력 검증 — 모든 도구는 zod 스키마를 선언합니다. 잘못된 입력은 CRM에 도달하기 전에 거부됩니다.

    • 감사 로거 (src/audit/auditLogger.ts) — 모든 호출(허용, 거부, 성공 또는 오류)은 테넌트, 주체, 도구 이름 및 결과와 함께 기록됩니다.

  6. 내부 API (src/crm/perfexClient.ts) — 테넌트 범위의 HTTP 클라이언트가 실제 Exir CRM API(Perfex CRM의 REST API, authtoken 헤더 인증)를 호출하고 결과를 도구의 출력으로 체인 위로 반환합니다.

Related MCP server: Nervora

프로젝트 구조

src/
  auth/oidc.ts            OAuth 2.1 / OIDC bearer-token verification
  tenant/tenantResolver.ts Tenant lookup + per-tenant CRM connection details
  permissions/permissionEngine.ts  Scope-based authorization
  audit/auditLogger.ts     Structured audit trail for every tool call
  middleware/rateLimiter.ts Per-tenant rate limiting
  crm/perfexClient.ts      Internal API client to the Exir CRM API
  tools/                   Tool Registry + one file per CRM domain
    customers.ts leads.ts tasks.ts invoices.ts
  mcp/server.ts            Wires tools -> permissions -> validation -> audit -> CRM
  http/app.ts              Express app: /healthz, POST /mcp
  index.ts                 Process entrypoint
tests/                     Vitest unit tests (permission engine, tool registry)

시작하기

npm install
cp .env.example .env   # fill in OIDC_ISSUER, CRM_API_BASE_URL, CRM_API_KEY, ...
npm run dev             # ts-node/tsx dev server on :3333

프로덕션 빌드 및 실행:

npm run build
npm start

또는 Docker를 통해:

docker compose up --build

테스트 실행:

npm test

새 도구 추가

  1. src/tools/ 아래의 관련 파일(또는 새 CRM 도메인을 위한 새 파일)에 registry.register({...}) 호출을 추가합니다. name, description, requiredScope, zod inputSchema, 그리고 PerfexClient를 호출하는 handler(crm, input)을 포함합니다.

  2. 새 파일인 경우 src/tools/index.ts의 buildToolRegistry()에 연결합니다.

  3. tests/tools.test.ts에 도구가 등록되었고 스키마가 잘못된 입력을 거부하는지 확인하는 테스트를 추가합니다.

다른 곳에서는 변경이 필요 없습니다 — 권한 부여, 검증 및 감사는 src/mcp/server.ts에 의해 등록된 모든 도구에 일반적으로 적용됩니다.

멀티 테넌시

src/tenant/tenantResolver.ts에는 모든 테넌트 ID를 .env의 단일 CRM 연결로 해석하는 EnvTenantStore 개발 대체가 포함되어 있습니다. 실제 멀티 테넌트 배포의 경우 테넌트 디렉터리(Postgres, 구성 서비스 등)에 대해 TenantStore 인터페이스를 구현하여 테넌트 ID -> { baseUrl, apiKey }로 매핑하고 src/http/app.ts의 tenantResolver(myStore)에 전달하세요.

보안 참고 사항

  • 테넌트 ID는 암호화 방식으로 검증된 액세스 토큰의 클레임에서만 신뢰되며, 신뢰할 수 있는 내부 네트워크 호출자(예: 로컬 개발)를 위해 TENANT_HEADER_FALLBACK=true가 명시적으로 설정되지 않는 한 클라이언트가 제공한 헤더에서는 절대 신뢰되지 않습니다.

  • 테넌트별 CRM API 키는 절대 기록되지 않습니다 (src/logger.ts는 Authorization, *.apiKey, *.token을 삭제합니다).

  • 모든 도구 호출은 두 번 검증됩니다. 먼저 MCP SDK가 도구의 JSON 스키마에 대해 검증하고, 그 다음 핸들러 내부의 zod.safeParse가 다시 검증합니다. 그 후에야 CRM API 호출이 이루어집니다.

  • 서버는 상태 없이 실행됩니다 (sessionIdGenerator: undefined). 각 HTTP 요청에 대해 새 MCP 서버 인스턴스가 생성되며, 해당 요청의 검증된 테넌트와 권한으로 범위가 지정됩니다. 따라서 테넌트 간에 누출될 수 있는 공유 세션 상태가 없습니다.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Peta Core

    dunialabs
    F
    license
    Not graded
    quality
    A
    maintenance
    A production-ready MCP gateway and control plane that provides credential vault, policy engine, audit logging, and managed runtime for routing tool calls between AI agents and downstream MCP servers.
    58
    -

  • Nervora

    sveselaj
    A
    license
    Not graded
    quality
    D
    maintenance
    A secure MCP gateway for enterprise AI tool execution, enabling governed invocation of business tools with authentication, RBAC, audit logging, PII redaction, and async processing.
    Apache 2.0

  • nice

    fainir
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides a secure MCP gateway for AI agents to access APIs without exposing raw credentials, with scoped access, audit logging, and OAuth support.
    MIT

  • datacrazy-mcp

    hiperbold
    A
    license
    Not graded
    quality
    D
    maintenance
    A multi-tenant MCP server that exposes DataCrazy CRM REST API as 63 auto-generated tools, allowing AI assistants to query leads, conversations, pipelines, and more through natural language.
    MIT