admina-mcp-server

MCP server for the Admina API.

Tools and API Documentation

Organization

• get_organization_info: Get information about the organization including name, unique name, status, and system language.

Devices

• get_devices: Return a list of devices with advanced search and filtering. Get Devices API

• create_device: Create a new device for an organization. Requires device type (subtype), asset number, and model name.

• update_device: Update an existing device's information including preset fields and custom fields.

• update_device_meta: Update device's meta information including assignment info (peopleId, status, dates) and location.

Device Custom Fields

• get_device_custom_fields: Get all custom fields configured for an organization's devices.

• create_device_custom_field: Create a new custom field for organization devices.

• update_device_custom_field: Update an existing device custom field configuration.

• delete_device_custom_field: Delete a device custom field configuration.

Identities

• get_identities: Return a list of identities. Get Identities API

• create_identity: Create a new identity. Requires employeeStatus, employeeType, firstName, lastName.

• get_identity: Get a single identity by ID. Optionally expand with customFieldsMetadata.

• update_identity: Update an existing identity by ID.

• delete_identity: Delete an identity by ID.

• get_identity_field_configuration: Get identity field configuration of an organization including preset field settings, field order, and source of truth metadata.

• get_identity_config: Get configuration for identity fields of a specific identity.

• check_identity_management_type: Determine the management type for an identity based on email or identityId.

• get_identities_stats: Get identities statistics including management type counts, HR master integration info, and domain lists.

• merge_identities: Merge identities in batch (supports up to 50 merge operations per request).

• unmerge_identities: Unmerge previously merged people or identity entities (supports up to 50 unmerge operations per request).

• bulk_update_identities: Bulk update multiple identities in a single request. Provide a list of identity IDs (1-50) and a set of field updates to apply to all of them.

• get_identity_history: Get the change history of a specific identity. Returns a paginated list of field-level changes, action types, sources, and actors.

• archive_identity: Toggle the archive flag for an identity by ID. Returns the updated identity.

• unregister_identity: Toggle the unregistered management type for an identity by ID. Returns the updated identity.

Services & Accounts

• get_services: Return a list of services integrations that belongs to organization along with a preview of accounts. Organization Services API

• get_service_accounts: Return a list of accounts for a specific service. Get Service Accounts API

• get_people_accounts: Return a list of all SaaS accounts belonging to a person. Get People Accounts API

Related MCP server: Attio MCP Server

Configuration

To configure the admina-mcp-server, you will need the organizationId and an API key. For more details on obtaining your API key, please refer to the Getting Started Guide.

The server supports two transports:

• stdio (default) — local subprocess, credentials from environment variables. Use this for Claude Desktop, Cursor, and similar clients.

• HTTP (Streamable HTTP) — remote server, credentials per request via headers. Use this for hosted deployments and multi-tenant setups. See docs/remote-mcp.md for the full spec.

MCP Client Configuration (stdio)

To run the server locally as a subprocess, add the following configuration to your MCP client settings:

{
  "mcpServers": {
    "admina-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@moneyforward_i/admina-mcp-server"
      ],
      "env": {
        "ADMINA_ORGANIZATION_ID": <Organization Id>,
        "ADMINA_API_KEY": <API Key>
      }
    }
  }
}

For local set up, run yarn build:dev and set the path to the root dir.

MCP Client Configuration (HTTP / Remote)

Start the server in HTTP mode:

admina-mcp-server --http --port 3000

Defaults: bind 127.0.0.1:3000, path /mcp. Override via --host, --port, or MCP_HTTP_HOST / MCP_HTTP_PORT env vars.

In HTTP mode the server is stateless: credentials are supplied per request via HTTP headers (Authorization: Bearer <API_KEY> and X-Admina-Organization-Id: <ORG_ID>). A single instance can serve many tenants.

Client configuration example (exact key names vary by client):

{
  "mcpServers": {
    "admina-remote": {
      "type": "http",
      "url": "https://your-deployment.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <API Key>",
        "X-Admina-Organization-Id": "<Organization Id>"
      }
    }
  }
}

See docs/remote-mcp.md for auth details, multi-tenant setup, security notes, and a curl smoke test.

Deployment (ECS Fargate)

The remote server is deployed as an ECS Fargate service in the vulcan account, behind an internal NLB and reached cross-account by Minabot via PrivateLink. The AWS resources are provisioned in aws-terraform; this repo owns the Dockerfile, the ECS task definition, and the CD workflows. Push to develop deploys test; push to main deploys prod. See docs/deployment.md for the full architecture, the infra contract, and prerequisites.

Releasing

Preparing a release

• Bump up a package version of package.json. A Git commit will be created automatically.

yarn version --new-version <new version>

• Push the change to the main branch as usual.

Publishing

Publishing is automatic. On push to main, the Publish to npm workflow publishes to npm (authenticated with the NPM_TOKEN repo secret) and creates the matching vX.Y.Z git tag and GitHub Release. It only publishes when the package.json version is not already on npm, so a yarn version bump is all that's needed — no manual GitHub Release step.