machship-mcp

Link Identities to Companies

machship_link_identities_to_companies

Assign companies and roles to identities to grant system access. Use this to link users to the correct company and permissions; administrator access required.

Instructions

Assign companies and roles to identities to give them access to the system. Requires administrator access.

Args:

links (array): Array of identity-company link objects, each with identityId, companyId, and roles

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": {
      "links": "<links>"
    },
    "name": "machship_link_identities_to_companies"
  }
}

Input Schema

Name	Required	Description	Default
`links`	Yes	Identity-company links 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.

Changed5 schema fields changedv1.0.1Nov 3, 2026

removedInput schema / properties / links / items / additionalProperties
```
Removed value: -false
```
addedInput schema / properties / links / items / properties / companyId / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / links / items / properties / identityId / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / links / items / properties / roles / 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

B3.4/5.0

Behavior3/5

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

Annotations already declare a non-read-only, non-destructive, non-idempotent, open-world mutation, so the description only needs to add context beyond that. It does add the admin-access requirement and the security consequence of the call, but it omits the most important behavioral detail for a non-idempotent link operation: what happens if an identity is already linked to that company (overwrite roles, merge, or error).

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

Conciseness4/5

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

The structure is good: purpose first, prerequisite second, argument summary last, with no filler sentences. The Args block largely duplicates schema field names, which is minor waste but aids quick scanning.

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

Completeness3/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 not be explained. For a non-idempotent, admin-gated bulk mutation, though, the description should cover batch behavior (all-or-nothing vs partial success) and the roles payload shape; those gaps matter for correct invocation.

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 coverage is 100% and each field carries its own description, so the baseline of 3 applies. The description merely restates the three field names; it does not explain the shape of the 'roles' entries, which the schema leaves as untyped objects with additionalProperties, so the one genuinely ambiguous part of the payload stays undocumented.

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 uses a specific verb and resource ('Assign companies and roles to identities') and states the outcome ('to give them access to the system'), so an agent can tell this is the access-granting counterpart to the unlink tool without opening the schema. It stops short of naming the sibling it mirrors (machship_unlink_identities_from_companies) or clarifying that this is a bulk operation on multiple identity-company pairs.

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 gives one concrete prerequisite ('Requires administrator access'), which is genuinely useful for routing. However, there is no guidance on when to use this versus creating an identity with company data, nor on whether it should be called repeatedly for additional links, leaving the agent to infer usage from the name.

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

Deploy Server