machship-mcp

Create Identities

machship_create_identities

Create MachShip identities, assign companies and roles, and keep all identities under one identity provider and organisation. Requires administrator access.

Instructions

Create identities in MachShip and assign companies and roles. All identities must belong to the same identityProvider and organisation. Requires administrator access.

Args:

identities (array): Array of identity objects, each with:
- givenName (string): First name (required)
- familyName (string): Last name (required)
- displayName (string): Display name (required)
- emailAddress (string): Email (required)
- identifyingClaim (string): Unique claim for identity provider (required)
- organisationId (number): Organisation ID (required)
- identityProviderId (number): Identity provider ID (required)
- owningCompanyId (number): Owning company ID (required)
- password (string, optional): Password
- uniqueId (string, optional): Unique ID
- userAndCompanyLinks (array, optional): Company/role links to create

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "identities": "<identities>"
    },
    "name": "machship_create_identities"
  }
}

Input Schema

Name	Required	Description	Default
`identities`	Yes	Identities to create

Output Schema

Name	Required	Description	Default
`errors`	No	Validation errors returned by Machship, if any
`object`	No	Response payload from the Machship API

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv1.0.1Nov 3, 2026
- removedInput schema / properties / identities / items / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / identities / items / properties / businessPhone / description
```
Added value: +"Business phone number"
```
- addedInput schema / properties / identities / items / properties / emailAddress / pattern
```
Added value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
```
- addedInput schema / properties / identities / items / properties / enableEmailNotifications / description
```
Added value: +"Enable email notifications for this identity"
```
- addedInput schema / properties / identities / items / properties / identityProviderId / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / identities / items / properties / mobile / description
```
Added value: +"Mobile number"
```
- addedInput schema / properties / identities / items / properties / notes / description
```
Added value: +"Additional notes about the identity"
```
- addedInput schema / properties / identities / items / properties / organisationId / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / identities / items / properties / owningCompanyId / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / identities / items / properties / phone / description
```
Added value: +"Phone number"
```
- addedInput schema / properties / identities / items / properties / position / description
```
Added value: +"Job position or title"
```
- addedInput schema / properties / identities / items / properties / userAndCompanyLinks / items / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
- changedOutput schema / (root)
```
Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "errors": {
+      "anyOf": [
+        {
+          "items": {},
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Validation errors returned by Machship, if any"
+    },
+    "object": {
+      "description": "Response payload from the Machship API"
+    }
+  },
+  "type": "object"
+}
```
First observedv1.0.0Jun 12, 2026

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=false, destructive=false, openWorld=true, idempotent=false, so the safety profile is covered. The description adds two things beyond that: administrator-level authorization is required, and all items in the batch must share the same identityProvider/organisation. It does not explain batch failure semantics (all-or-nothing vs partial), duplicate-claim handling, or that passwords are submitted in plaintext.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The prose lead is front-loaded and efficient, with the auth requirement and the shared-provider constraint in the right place. However, the bulk of the description is an Args enumeration that duplicates a 100%-covered schema field-for-field, so a meaningful fraction of the text does not earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations cover the mutation safety profile. The description adds authorization and batching constraints, which is what an agent needs to invoke this correctly. The remaining gap is batch-level behavior on partial failure or duplicate identities, which matters for an array-input creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every nested field (givenName, identifyingClaim, userAndCompanyLinks, etc.) is already documented with requiredness and types in the schema. The Args block largely restates that same field list, adding no format examples, link-object structure, or validation nuance. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Create identities in MachShip') plus a secondary effect ('assign companies and roles'), which separates it from machship_update_identity and machship_link_identities_to_companies. It also states a cross-item constraint (same identityProvider and organisation) that no sibling could satisfy. It does not explicitly name the sibling to use when the identity already exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a prerequisite ('Requires administrator access') and a batching constraint ('All identities must belong to the same identityProvider and organisation'), which helps gate when the call is legal. It gives no guidance on when to prefer machship_update_identity or machship_link_identities_to_companies over creating new identities, so the alternative-selection path is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server