ServiceNow Managed MCP Server

For a managed server, set the authentication method inside the --managed.config JSON. The auth field is required.

Replace <oauth-client-id> with the client ID from your ServiceNow OAuth application registry, and servicenow-prod with the name of the OAuth Provider you configured.

Replace <cluster-id> with your cluster ID and $TOKEN with a gateway access token.

The agent typically calls lookup_user and get_field_choices first to resolve caller_id and a valid category value.

Instances commonly require a close code before an incident can be resolved or closed. That requirement isn’t part of the table schema get_table_schema reads, so the server can’t discover it. Declare it in incident_state_requirements instead. An unconfigured requirement isn’t enforced.

A declared requirement is checked before anything is sent, so a missing field comes back naming the field, and the agent can ask a person for it instead of interpreting an upstream rejection. The check has a wider reach than one tool, and it is forgiving about case:

Some instances don’t use state as the column that actually drives an incident’s state. On those, a write to state can report success while the incident doesn’t move. Set incident_state_field to the column that does drive state, commonly incident_state, and transition_incident writes that column instead.

Only the column changes. The agent still passes a state name in words, and the name resolves against the choices that column defines. Because a state can still reach the server as a raw state key in additional_fields, a configured requirement covers both column names, and transition_incident drops every state key from additional_fields before it assigns the resolved value, so one call can’t carry two states.

A misspelled column doesn’t fail quietly. Write verification treats the configured column like any other incident field, so a returned record that holds the write’s other fields but not that column reports the state under not_applied.

The search runs two passes: one over each item’s name, short description, and category, and one over the option values on items' request forms. The second pass is what reaches a product that is a choice on a general item rather than an item of its own. A result found that way carries the matching option, so an agent can pre-fill it instead of asking again.

Treat the results as candidates rather than as the whole catalog. The response caps them (10 by default, 50 at most) and sets results_truncated when more items matched than it returned, so an item missing from a truncated result is not an item the catalog lacks. Narrow the query to a product name, or pass a category to scope a second pass the way the portal’s own navigation does.

A separate flag, option_search_unavailable, reports that the option-value pass couldn’t run at all. A false value there is weaker than it looks: an instance that filters rows out by permission answers the query normally, which looks the same as nothing matching.

The form that get_catalog_item returns lists each variable with its name, the question the form asks, its type, whether it’s mandatory, its default value, help text, the table a reference value must come from, its allowed values, and its position on the form. Asking in that order follows the form the user would otherwise have filled in.

The mandatory flag comes from the variable’s definition, so a UI policy can make a further variable mandatory once the form is being filled in. An unexpected rejection doesn’t mean the list was wrong.

The response also reports whether the item is still active. A retired item keeps a readable form but can’t be ordered, so check this before collecting values. Search only ever returns live items, so it matters when a sys_id came from somewhere else, or the item retired since.

Key every submitted value by the variable’s name rather than by the label the form shows, and pass the stored value rather than its display label. A mandatory variable that has a default value still needs that value passed explicitly, so the form that reaches ServiceNow is the form the agent reasoned about.

Both submission tools check the values against the form before sending anything, so a missing mandatory value or a name the form doesn’t carry comes back naming the variable, rather than as a rejection that identifies no field. A submission refused this way sent nothing, so correcting the arguments and calling again is safe.

When the form came back partial, only the mandatory-value half of that check runs. An unrecognized name then reaches ServiceNow, because refusing it would block a submission that the item would have accepted.

To order more than one of an item, pass a quantity with the submission. It defaults to 1, and 100 is the most you can order in a single call.

The submit_catalog_request tool returns the requested-item numbers, which begin with RITM. Those are the identifiers to give the user. The response also carries the request number, which begins with REQ, but that’s the container the requested items hang off, and isn’t what a user is asking for.

The submit_record_producer tool returns the table the producer wrote to, along with the created record and its number. Check the table before describing what was created, because a producer chooses its own target, and an idea and an incident reach different teams.

Two limits apply before you rely on either result. A catalog request confirms only that the request and its items exist. It says nothing about whether the form holds the values that were sent, because those live on separate option rows that this server doesn’t read. A record producer does compare the values it sent against the record it read back, because it writes a real record whose columns come back on a read. Even then, a producer script can map a variable to a different column, and the report marks a variable remapped that way as unconfirmed rather than as stored.

When a form couldn’t be read completely, get_catalog_item marks the response as incomplete. A variable missing from an incomplete form isn’t a variable the item doesn’t ask for, and an empty allowed-value list isn’t evidence that a value is invalid. The same applies to a catalog search whose option-value pass couldn’t run: the result is partial, not proof that the catalog holds no such thing.