This section answers common questions about MCP configuration, security, and operational practices.

Why are write methods missing by default?

Write methods are excluded by default for safety. Unless explicitly included, non-GET operations are disabled to prevent unintended data changes.

Can I hot reload the OpenAPI specification?

Hot reload is not supported. Restart the server or profile after making changes to the OpenAPI specification. This ensures deterministic tool catalogs.

How do I add a new helper tool?

Implement the logic under src/tools/. Register the tool in create_server following the pattern used for prompt or tag tools. Optionally, add scope requirements for access control.

Can I disable the response guard?

Yes, you can disable it by setting runtime.http.response_guard.enabled=false. However, this is strongly discouraged in production. Instead, adjust limits to handle large responses safely.

Is payload logging safe?

Payload logging can expose sensitive data. Keep include_payloads=false outside controlled debugging environments.

How do I run multiple profiles simultaneously?

Assign unique host ports using the --port option while using up command for profile startup. Each profile will have its own directory and container name.

Why export instead of copying the generated folder directly?

Export normalizes content, pins image digests, strips development artifacts, and creates a consistent deployment package suitable for production.

Does JWKS support algorithm pinning?

Yes. Use security.authentication.service_account.algorithms to restrict accepted signing algorithms.

How do I test mTLS quickly?

Generate certificates with --mtls and use the bundled client:
./mcpgen client <name>

For external clients, mount certs/dev/client.pem and the key according to the TLS options of your tool.

How do I avoid certificate hostname warnings?

Use the --extra-hostnames flag when generating certificates to include all domains your clients will use.

Examples:
Single domain:
./mcpgen up --quick --tls --extra-hostnames api.example.com

Multiple domains:
./mcpgen up --quick --tls --extra-hostnames "api.example.com,staging.example.com,myapp.local"

For mTLS:
./mcpgen up --quick --mtls --extra-hostnames "api.example.com,staging.example.com"

The generated certificates include both localhost and your specified hostnames as Subject Alternative Names (SAN) to prevent SSL warnings when clients connect using different hostnames.

What is the difference between export bundles, such as development, production, strictly-production?

The differences are as follows:
Bundle type Description
Development Includes all artifacts such as context, prompts, private keys, and tokens for development convenience
Production Production-safe bundle with context and prompts, excludes private keys and tokens
Strictly-production Minimal bundle with no context, prompts, private keys, or tokens. Production cleanup applied

For most production deployments, use:

./mcpgen export <profile_name> --bundle prod

What is the difference between export and export-tar?

Both export and export-tar create deployment bundles with the same content options and support the same --bundle options for development, production, and strictly-production. Here are some differences:
Command Description
export Creates a directory structure suitable for Docker Compose deployment
export-tar Creates a compressed tarball for easier distribution and archival

Use export-tar when transferring between systems or for automated deployments.

How do I manage multiple service account tokens?

Use the sa-token and sa-tokens commands for token management as follows:
Create named token:
./mcpgen sa-token <profile_name> --name admin --scopes api.read api.write

List all tokens:
./mcpgen sa-tokens <profile_name> --json

Set primary token:
./mcpgen sa-token <profile_name> --name admin --set-primary

Remove token:
./mcpgen sa-token <profile_name> --name admin --remove

Can I generate OpenAPI specs from OpenEdge Business Entities?

Yes. Use the openapi-gen command:
From local catalog:
./mcpgen openapi-gen <catalog.json> -o <openapi.yml>

From remote endpoint:
./mcpgen openapi-gen http://localhost:8810/web/oemanager/catalog -o <openapi.yml>

The openapi-gen command generates complete OpenAPI 3.0.3 specifications based on Business Entity definitions.

What should I do if a smoke test fails when running the ./mcpgen up or ./mcpgen restart commands?

Do not ignore smoke test failures. Investigate the cause before bypassing the smoke test. After investigating, if you have confirmed a valid reason for the failure, such as a timeout, or are unable to determine the cause, you may proceed with the following workaround:
  1. Rerun the command with the --no-smoke option, for example:
    ./mcpgen up --no-smoke
    		 
    ./mcpgen restart --no-smoke <container_name>
  2. Manually call a tool to verify access:
    ./mcpgen client --tool <tool_name> --json <profile>
    If this call fails, see the corresponding entry in the Troubleshooting reference table.

How do I prepare a profile for production deployment?

Use the harden command to remove development artifacts:

Remove client tools:
./mcpgen harden <profile_name> --remove-client

Remove private keys:
./mcpgen harden <profile_name> --drop-private

Remove tokens:
./mcpgen harden <profile_name> --drop-token

Full hardening:
./mcpgen harden <profile_name> --remove-client --drop-private --drop-token

How do I debug HTTP communication issues?

Use the --debug flag with the client command:
./mcpgen client <profile_name> --debug
./mcpgen client <profile_name> --tool myTool --args '{"id":123}' --debug
Debug output includes:
  • Full Docker command executed
  • HTTP request details (method, URL, headers with sensitive values masked)
  • HTTP response details (status code, headers, body preview)
  • MCP protocol message flow
  • Timing information
Note: Always redact sensitive information before sharing logs.

How do I use different service account tokens for testing?

The client command supports named token selection:
./mcpgen client <profile_name> --sa-token admin --tool sensitiveOperation
./mcpgen client <profile_name> --sa-token readonly --tool listData

The client command allows testing with different permission levels without recreating profiles.

How do I rotate service account keys completely?

Use remint-all to generate a new key pair and re-mint all tokens:
./mcpgen remint-all <profile> --days 90 --scopes mcp_access api.read

This command creates fresh keys and regenerates all existing tokens with the new keypair.

Are SSE and streamable HTTP interchangeable?

Yes. Choose based on client capability. Streamable HTTP is the default for simplicity. Enable SSE through configuration or the MCP_USE_SSE environment variable.

Does rate limiting apply per tool?

Rate limiting is currently applied per inbound request, which means each tool invocation is treated as an individual request. If you need to distinguish between tools, you can review the server logs for detailed information.

Are denies cached?

Denials are not cached. Each incoming request consumes or checks the bucket state in real time. This ensures accurate enforcement of rate limits without relying on cached decisions.

Can I exempt a service account?

Service account exemption is not supported yet. The roadmap includes an optional scope-based exemption field that will allow administrators to configure exemptions in future releases.

Do I need both summary and description? in openAPI specification?

Yes. The summary provides a concise label for the operation, while the description supplies actionable context, assumptions, and edge cases.

Can I omit the title in schemas?

Avoid omitting the title. It improve readability in helper tools and catalog listings. Including a title makes schemas easier to identify and reuse.

Should I inline trivial response objects in API documentation?

Prefer components even for small shapes if reused more than once. Using components deduplicates definitions and clarifies intent. Inline objects should only be used when they are unique and not repeated.

How do I distinguish partial updates?

Use the PATCH method with a separate schema or application/merge-patch+json. Document the semantics clearly so consumers understand how partial updates differ from full replacements.

Must every schema property declare a type?

Yes. Omitting the type prevents reliable parsing and weakens validation. Always specify at least the type and include the format when meaningful. This practice strengthens validation and improves prompt shaping.

Can I redact specific fields selectively in logs?

Not yet supported. The recommended workaround is to disable include_payloads and rely on upstream sanitization to remove sensitive data before logs are ingested.

Does structured logging mode guarantee ordering?

Ordering is preserved per container stdout only. There is no global ordering across replicas.

Are multi-line logs emitted?

No. Each event is emitted as a single-line JSON record. This design simplifies ingestion and ensures compatibility with log aggregation tools.

Escalation checklist before filing an issue

Before raising a support ticket, complete these steps:
  • Run ./mcpgen doctor to verify system dependencies and configuration.
  • Capture the failing tool invocation including inputs, truncated output, and correlation ID.
  • Confirm configuration matches documented properties and does not contain typos.
  • For authentication issues, specify whether a service account is required, include JWKS settings, and provide a sample (with sensitive data redacted) JWT header.
  • Use the --debug flag for detailed HTTP communication logs when applicable.

How to collect diagnostics

Follow these steps:
  1. Run the following commands to gather diagnostic information:
    ./mcpgen check <profile_name>
./mcpgen logs <profile_name> --tail=200 > issue.log
  2. Redact secrets such as tokens and private keys.

  3. Attach a sanitized mcp_server_config.json file to the support ticket.

Use the --debug flag for HTTP troubleshooting

The mcpgen client command supports a --debug flag that shows detailed HTTP request and response information:
./mcpgen client <profile_name> --debug
./mcpgen client <profile_name> --tool listProducts --args '{"limit":3}' --debug
Use --debug when diagnosing:
  • Authentication or authorization failures
  • Unexpected API responses
  • Header propagation issues
  • Downstream HTTP communication problems
  • Token exchange issues
  • SSL or TLS handshake problems
Note: Always redact sensitive information, including tokens, keys, PII, and so on, before sharing logs.

Targeted 400 invalid params instrumentation

If you encounter repeated Invalid params errors without a clear cause, follow these steps:
  1. Enable the diagnostics middleware:
    {
  "runtime": { "middleware": { "validation_diagnostics": { "enabled": true } } },
  "logging": { "loggers": { "validation.diagnostics": "INFO" } }
}
  2. Reproduce the failing call and inspect logs for lines like:
    invalid_params: method=tool.invoke message=Invalid params: missing field 'id' arg_keys=['filter','top']

  3. Disable diagnostics afterward by setting enabled=false to reduce noise.

CLI exit codes quick reference

The following table lists the exit codes and their meanings:
Code Meaning
0 Success
1 Generic error or configuration validation failure
2 Missing profile or resource
Non-zero codes indicate failure. Scripts should treat any non-zero exit code as an error.