# AMS360 MCP Server

MCP server for Vertafore AMS360 WSAPI v3, implemented in TypeScript with [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-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

```bash
npm install
npm run build
```

To run directly from source during development:

```bash
npm run dev
```

To run the compiled server:

```bash
npm start
```

## Configuration

Set these environment variables:

```bash
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:

```bash
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:

```bash
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`:

```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:

```json
{
  "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`:

```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](https://link.vertafore.com/VERTAFORE/documentation/AMS360/introduction)
- AMS360 WSAPI setup help: [help.vertafore.com/AMS360/content/contextsensitive/download-integration/cswebserviceapisetup.htm](https://help.vertafore.com/AMS360/content/contextsensitive/download-integration/cswebserviceapisetup.htm)
- AMS360 developer portal TOC: [api.apps.vertafore.com/.../entities/AMS360/toc](https://api.apps.vertafore.com/developer-portal/v1/DEVELOPER-PORTAL-WEB-UI/VERTAFORE/entities/AMS360/toc)
- AMS360 WSAPI bundle metadata: [api.apps.vertafore.com/.../entities/AMS360/docs/AMS360:WSAPI:22f503](https://api.apps.vertafore.com/developer-portal/v1/DEVELOPER-PORTAL-WEB-UI/VERTAFORE/entities/AMS360/docs/AMS360:WSAPI:22f503)