ams360-mcp-server

AMS360 MCP Server

MCP server for Vertafore AMS360 WSAPI v3, implemented in TypeScript with @modelcontextprotocol/sdk and a real SOAP 1.1 client for AMS360's WCF endpoint.

What it does

This server exposes the following MCP tools:

• search_clients(query)
• get_client(clientId)
• get_policies(clientId)
• get_renewals(startDate, endDate)
• get_activities(filter)

Under the hood it uses the public AMS360 WSAPI v3 contract:

• Login to establish a session
• CustomerGetById
• CustomerGetByNumber
• CustomerGetListByNamePrefix
• PolicyGet
• PolicyGetListByCustomerId
• PolicyGetListByCustomerNumber
• PolicyGetListByPolicyNumber
• CustomerSuspenseGetListByCustomerId
• CommonSuspenseGetListByEntityId
• PersonalNoteGetList
• LineOfBusinessGetByCode

Important WSAPI notes

The public Vertafore AMS360 WSAPI v3 docs currently describe a single SOAP endpoint:

• https://wsapi.ams360.com/v3/WSAPIService.svc

Authentication is not plain REST-style auth. The documented flow is:

1. Call Login with AgencyNo, LoginId, Password, and optionally EmployeeCode.
2. Read the WSAPISession SOAP header from the login response.
3. Send that WSAPISession header with subsequent requests.

This server follows that flow and also supports optional HTTP Basic auth for agencies that place WSAPI behind an additional HTTPS auth layer.

Limitations from the public docs

Two of the requested concepts are not fully exposed by the current public WSAPI v3 surface:

• The docs show CustomerActivityInsert and CommonActivityInsert, but not an activity-list retrieval operation.
• The docs do not publish a global agency-wide renewal date-range query.

Because of that:

• get_activities is implemented against the retrievable WSAPI entities that agencies commonly use for reminders: customer suspenses, common suspenses, and personal notes.
• get_renewals returns a structured docs-based limitation message instead of pretending a complete renewal feed exists when it does not.

Prerequisites

• Node.js 20+ recommended
• AMS360 WSAPI credentials created in AMS360
• Your agency number

Install

npm install
npm run build

To run directly from source during development:

npm run dev

To run the compiled server:

npm start

Configuration

Set these environment variables:

export AMS360_AGENCY_NO="YOUR_AGENCY_NO"
export AMS360_USERNAME="YOUR_WSAPI_LOGIN_ID"
export AMS360_PASSWORD="YOUR_WSAPI_PASSWORD"
export AMS360_ENDPOINT_URL="https://wsapi.ams360.com/v3/WSAPIService.svc"

Optional variables:

export AMS360_EMPLOYEE_CODE="ABC"
export AMS360_TIMEOUT_MS="30000"
export AMS360_POLICY_DETAIL_LIMIT="25"
export AMS360_DEBUG="false"

Optional HTTP Basic auth, if your agency front-ends WSAPI with another auth layer:

export AMS360_HTTP_AUTH_MODE="basic"
export AMS360_HTTP_USERNAME="basic-auth-user"
export AMS360_HTTP_PASSWORD="basic-auth-password"

Aliases supported by this server:

• AMS360_AGENCY_URL as an alias for AMS360_ENDPOINT_URL
• AMS360_LOGIN_ID as an alias for AMS360_USERNAME

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "ams360": {
      "command": "node",
      "args": [
        "/absolute/path/to/ams360-mcp-server/dist/index.js"
      ],
      "env": {
        "AMS360_AGENCY_NO": "YOUR_AGENCY_NO",
        "AMS360_USERNAME": "YOUR_WSAPI_LOGIN_ID",
        "AMS360_PASSWORD": "YOUR_WSAPI_PASSWORD",
        "AMS360_ENDPOINT_URL": "https://wsapi.ams360.com/v3/WSAPIService.svc"
      }
    }
  }
}

If you want Claude Desktop to launch it from the package directory instead:

{
  "mcpServers": {
    "ams360": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/ams360-mcp-server/src/index.ts"
      ],
      "env": {
        "AMS360_AGENCY_NO": "YOUR_AGENCY_NO",
        "AMS360_USERNAME": "YOUR_WSAPI_LOGIN_ID",
        "AMS360_PASSWORD": "YOUR_WSAPI_PASSWORD"
      }
    }
  }
}

Claude Code

Add the same server definition to .claude.json:

{
  "mcpServers": {
    "ams360": {
      "command": "node",
      "args": [
        "/absolute/path/to/ams360-mcp-server/dist/index.js"
      ],
      "env": {
        "AMS360_AGENCY_NO": "YOUR_AGENCY_NO",
        "AMS360_USERNAME": "YOUR_WSAPI_LOGIN_ID",
        "AMS360_PASSWORD": "YOUR_WSAPI_PASSWORD",
        "AMS360_ENDPOINT_URL": "https://wsapi.ams360.com/v3/WSAPIService.svc"
      }
    }
  }
}

Tool behavior

search_clients(query)

Best-effort search strategy:

• GUID -> CustomerGetById
• numeric string -> CustomerGetByNumber
• text -> CustomerGetListByNamePrefix
• policy-looking string -> PolicyGetListByPolicyNumber, then hydrate matched customer records

get_client(clientId)

Fetches a full customer record by:

• customer GUID, or
• customer number

get_policies(clientId)

Returns:

• policy summaries for all matched policies
• hydrated policy details for up to AMS360_POLICY_DETAIL_LIMIT policies
• line-of-business enrichment via LineOfBusinessGetByCode

Important:

• policy summaries are returned for all matched policies
• full PolicyGet detail is only fetched for the first AMS360_POLICY_DETAIL_LIMIT policies
• the default detail limit is 25
• the tool output includes detailHydrationTruncated and detailHydrationMessage when the detailed set is partial

get_activities(filter)

Supported filter routes:

• {"customerId":"<guid>"} -> CustomerSuspenseGetListByCustomerId
• {"entityId":"<id>","entityType":<short>} -> CommonSuspenseGetListByEntityId
• {"source":"personalNotes","dateFrom":"2026-01-01","dateTo":"2026-01-31"} -> PersonalNoteGetList

Important:

• this tool does not default to personal notes when the filter is empty
• to retrieve personal notes, set source to "personalNotes" explicitly

get_renewals(startDate, endDate)

Returns a structured limitation response explaining that the public WSAPI v3 docs do not expose a true agency-wide renewal date-range query. This is returned as a normal tool response, not a transport/tool failure.

References

• Vertafore AMS360 API introduction: link.vertafore.com/VERTAFORE/documentation/AMS360/introduction
• AMS360 WSAPI setup help: help.vertafore.com/AMS360/content/contextsensitive/download-integration/cswebserviceapisetup.htm
• AMS360 developer portal TOC: api.apps.vertafore.com/.../entities/AMS360/toc
• AMS360 WSAPI bundle metadata: api.apps.vertafore.com/.../entities/AMS360/docs/AMS360:WSAPI:22f503