MCP Clients

MCP Client Integration Guide

This guide is for WordPress-native MCP/Abilities clients that consume Saltus Framework abilities from an active WordPress site.

Saltus registers saltus/* abilities inside WordPress. Clients should treat the ability definitions as the source of truth for available tools, input schemas, permissions, and transport metadata.

Client Goals

A good Saltus MCP client should:

• discover available saltus/* abilities before planning actions
• check site health before making a workflow plan
• inspect models and meta fields before reading or writing content
• use normalized metadata paths when reasoning about nested custom fields
• handle WordPress capability failures without retry loops
• respect rate limits and cacheable read operations
• ask for explicit user confirmation before destructive or broad writes

Recommended Call Flow

Use this sequence for most client sessions:

1. Call saltus/get-health
2. Call saltus/list-models
3. Call saltus/list-meta-fields
4. Choose the relevant model
5. Call saltus/get-model or saltus/get-meta-fields for model-specific detail
6. Read content with saltus/list-posts, saltus/get-post, saltus/list-terms, or settings tools
7. Propose changes to the user
8. Execute writes only after the target model, fields, and permissions are clear

Discovery

Clients should discover abilities from WordPress and filter for the saltus/ prefix. Every Saltus ability includes metadata:

{
  "meta": {
    "mcp_tool": "list_models",
    "namespace": "saltus-framework/v1",
    "transport": "wordpress-rest",
    "show_in_rest": true
  }
}

Health First

Call saltus/get-health at the start of a session. A healthy response confirms that Saltus' runtime controls are available.

Health signal	Client behavior
status: ok	Continue normally
status: degraded	Prefer read-only planning
High error_rate	Inspect permission and input errors
High latency	Reduce broad listing calls

Model Discovery

Use saltus/list-models to discover post types and taxonomies. Clients should not assume a model exists based only on a user phrase.

• Map user language to model names after reading model labels and slugs
• Prefer exact model slugs when calling tools
• If multiple models are plausible, ask the user to choose

Metadata Discovery

Use saltus/list-meta-fields for site-wide field discovery. Use saltus/get-meta-fields for one post type.

Saltus returns both raw and normalized metadata:

• meta: raw Saltus/Codestar model configuration
• normalized.fields: flattened field paths for client reasoning
• normalized.rest_meta_keys: REST-writable roots and type information

Clients should prefer normalized.fields when explaining or mapping field-level work.

Safe Read Patterns

1. saltus/list-posts with post_type, search, status, and pagination
2. Ask the user to confirm the target when ambiguous
3. saltus/get-post with the confirmed post_id

Safe Write Patterns

Recommended write flow:

1. Read current model and metadata
2. Read the target post or settings
3. Build a minimal patch
4. Summarize the planned mutation to the user
5. Execute the mutation
6. Read the object again to confirm the result

Destructive Actions

saltus/delete-post, saltus/reorder-posts, and settings updates can materially change the site. Require explicit confirmation for:

• force deletion
• bulk deletion
• reordering more than a small visible set
• settings updates
• writes to serialized or nested meta

Permission Failures

Failure	Likely cause	Client response
rest_forbidden	Current user lacks capability	Explain the required access and stop
invalid_params	Missing or malformed arguments	Fix arguments once, then retry
model not found	Model not registered or not visible	Ask for a different model
write denied	User can read but not mutate	Offer a read-only summary

Do not retry permission failures repeatedly.

Rate Limits

Saltus rate limiting protects WordPress from excessive ability calls. When a call returns a rate-limit error:

• Stop parallel calls after the first rate-limit error
• Use the returned retry_after value when available
• Prefer cached or already-read context while waiting

Caching

Saltus may cache read-only ability responses in WordPress transients. For workflows that must confirm a mutation:

1. Execute the write
2. Let Saltus clear its MCP cache
3. Read the changed object again

Anti-Patterns

• Guessing post type slugs without list_models
• Writing meta before checking normalized metadata
• Retrying permission failures
• Using large list queries as a discovery shortcut
• Force deleting without explicit confirmation
• Treating health ok as proof that all model-scoped capabilities are enabled