Overview ✨
Liongard offers two access models for partners:
REST API for integrations, automation and system-to-system communication
MCP Server for AI and agent-based access via the Model Context Protocol
These models complement each other but are not interchangeable. Each uses a different authentication pattern, serves a different purpose and should be chosen based on the partner's use case.
✅ Use REST API when you need:
| 📘 Use MCP Server when you need:
|
⚠️ Important: REST API credentials should not be used against the MCP endpoint, and MCP credentials should not be used against REST endpoints. Partners should treat these as separate access models with separate security and governance requirements.
Purpose and Scope
This article helps partners answer four common questions:
Which Liongard access model should I use?
How do REST API and MCP authentication differ?
How does permission scoping work for each model?
What security, billing, and implementation considerations should partners plan for?
This guide covers high-level design decisions, authentication patterns, governance, token behavior, usage considerations, and authoritative references for follow-up reading.
REST API vs. MCP Server: Key Differences and Partner Considerations
Area | REST API | MCP Server | Partner Impact |
Primary use | Automation and integrations | AI tools and agent workflows | Choose based on whether the workflow is deterministic or AI-assisted |
Endpoint family | /api/v1, /api/v2 | /api/mcp | Do not mix endpoint and token types |
Auth format | X-ROAR-API-KEY | Authorization: Bearer | Headers and credential handling differ |
Identity model | User-bound | Tenant-wide MCP credential model | Permission behavior differs significantly |
Typical access behavior | Reflects user role and changes | Managed through MCP token configuration | Token governance must be intentional |
Common partner scenario | PSA sync, exports, operational scripts | Cursor, VS Code, n8n, Claude Code, Copilot Studio | Match the technology to the operating model |
Choosing the Right Access Model: REST API vs. MCP Server
When Partners Should Use the REST API
The REST API is the right choice when a partner needs structured, repeatable, system-driven access to Liongard data.
Use it for integrations between Liongard and other platforms
Use it for scheduled data extraction or transformation workflows
Use it when the integration should follow a specific user’s permission model
Use it when the consuming system expects conventional REST endpoints and headers
For many MSP operational workflows, the REST API remains the most practical option because it is predictable, scriptable, and well-suited to middleware and reporting pipelines.
ℹ️ Partner guidance: For long-lived automations, use a dedicated service or integration user where appropriate so access is easier to manage and review over time.
When Partners Should Use the MCP Server
The MCP Server is the right choice when a partner wants to connect Liongard to an AI-capable client or orchestration layer that uses the Model Context Protocol.
Use it for AI copilots, assistants, and agent workflows
Use it when the workflow is query-driven and read-only in nature
Use it when users benefit from natural-language access to Liongard context
Use it when MCP-native tools are already part of the partner’s delivery model
This model is especially valuable for partners building higher-value advisory or co-managed experiences, because it can expose relevant Liongard intelligence in a governed and efficient way without requiring a custom export layer for every use case.
In general, the MCP Server is less about traditional integration and more about making Liongard data available to AI-enabled workflows in a controlled, purposeful way.
Authentication Methods: REST API vs. MCP Server
REST API authentication
REST API requests use a Liongard API credential in the request header.
X-ROAR-API-KEY: [ACCESS_KEY_ID]:[ACCESS_KEY_SECRET]
Example request pattern:
GET /api/v1/environments HTTP/1.1
Host: [instance].app.liongard.com
X-ROAR-API-KEY: [ACCESS_KEY_ID]:[ACCESS_KEY_SECRET]
Accept: application/json
In this model, the request operates according to the permissions associated with the user who owns the token.
MCP Server authentication
MCP requests are sent to the MCP endpoint and use a bearer-style authorization header.
POST /api/mcp HTTP/1.1
Host: [instance].app.liongard.com
Authorization: Bearer [ACCESS_KEY_ID]:[ACCESS_KEY_SECRET]
MCP-Protocol-Version: 2025-11-25 Content-Type: application/json
Partners should also be aware that Liongard provides OAuth guidance for supported MCP flows, which may be preferable for some client environments.
📕 Recommended approach: Where MCP clients support OAuth well, partners should consider it to reduce static secret distribution and improve credential governance.
Permissions and Access Scope: REST API vs. MCP Server
Although both the REST API and MCP Server provide access to Liongard platform data, they differ in how permissions are applied, how access is scoped, and how credentials are managed.
Understanding these differences is important for partners to ensure that integrations operate with the appropriate level of access while maintaining security and administrative control.
REST API Permissions and Access Scope
Liongard REST API access follows a user-based permission model, meaning that the permissions available through an API credential are associated with the Liongard user identity under which the credential was generated.
As a result, the API's effective access is governed by the user's assigned role and permissions within the Liongard platform.
Key considerations include:
Role-Based Access: REST API requests are subject to the permissions associated with the underlying Liongard user account. If the user's role or permissions are modified, subsequent API requests are expected to reflect those changes.
User Account Status: Because API access is associated with a user identity, disabling or deactivating that account will prevent its credentials from continuing to provide an active access path.
Permission Inheritance: REST API access follows the existing user permission structure, helping ensure that integrations do not exceed the permissions granted to the associated user.
Access Management: Administrators can manage the underlying user's role and account status as part of their existing access governance processes.
When this model is useful:
This approach is particularly beneficial when partners want API access to remain associated with a specific user identity and governed through Liongard's existing user permission structure.
For example, if a partner creates an integration using credentials associated with a user who has limited access to certain environments, the integration should operate within those same permission boundaries.
MCP Server Permissions and Access Scope
Unlike the REST API's user-based permission model, MCP Server access follows a separate credential and access management approach.
As outlined in the Liongard MCP Integration Guide, MCP access is not scoped by individual user permissions in the same manner as REST API user tokens. Instead, access is managed through the MCP credential model and its associated configuration.
This distinction is particularly important because MCP credentials may be used by AI assistants, automated agents, or other MCP-compatible applications rather than being directly associated with an individual Liongard user's permissions.
Key considerations include:
Credential-Based Access Management: MCP credentials should be managed as dedicated integration credentials rather than personal user tokens. Their access behavior is determined by the MCP authentication and configuration model.
Access Scope Configuration: Partners should carefully review the available scope and configuration options when creating MCP credentials to ensure access aligns with the intended integration requirements.
Environment Selection: Partners should verify which Liongard environments are accessible through the MCP integration and ensure that the configured access does not extend beyond the intended operational scope.
Credential Lifecycle Management: MCP credentials should be securely stored, periodically reviewed, rotated when appropriate, and revoked when an integration is no longer required.
Administrative Oversight: Because MCP access does not follow the same user-based permission boundaries as REST API access, partners should establish clear ownership and administrative controls for each MCP integration.
When this model is useful:
This approach is particularly relevant for partners implementing AI-powered integrations or automated workflows that require access to supported Liongard capabilities through an MCP-compatible client.
For example, a partner connecting an AI assistant to Liongard should review the MCP credential configuration and environment access settings before enabling the integration, rather than assuming the assistant will automatically inherit the permissions of the individual user interacting with it.
📔 Governance Takeaway: Unlike REST API credentials, which follow the permissions of an associated Liongard user, MCP credentials operate under a separate access management model. Partners should therefore apply additional administrative oversight, consistent naming conventions, credential rotation procedures, and careful environment scoping to maintain secure and controlled access to Liongard data.
Environment Scoping and Access Design
When creating MCP credentials, partners can select specific Liongard environments to define the integration's access scope. This allows partners to determine whether an MCP integration requires broader tenant-wide visibility or access limited to selected environments.
To maintain appropriate access controls, partners should configure MCP credentials based on the intended use case and follow the principle of least privilege.
Recommended Access Patterns
Internal Operations Access: Provides trusted internal teams with broader environment visibility for administration, troubleshooting, and reporting.
Team-Specific Access: Limits access to environments associated with a particular team, region, customer group, or automated workflow.
Restricted Customer-Facing Access: Provides narrowly scoped access for delegated or co-managed integrations, helping prevent unintended visibility into other customer environments.
Environment Scope Validation
Before deploying an MCP integration, partners should verify that the selected environment scope is applied correctly and that the integration cannot access environments outside its intended boundaries.
Where environment groups are referenced, partners should confirm their availability and supported behavior within their Liongard tenant before relying on them for access restrictions.
✅ Best Practice: Use separate MCP credentials for different integrations or workflows, apply the narrowest supported environment scope, and periodically review access to ensure it remains appropriate.
Commercial and Usage Considerations
When planning an MCP Server integration, partners should consider both access requirements and usage-related costs to ensure the solution remains efficient, scalable, and cost-effective.
Liongard's MCP offering includes token and credit-based usage concepts. Understanding these considerations can help partners select the appropriate access model and manage consumption effectively.
Key considerations include:
Token and Credit Management: MCP usage is tracked through a credit-based model. Partners should understand how credits are consumed and plan accordingly.
Subscription and Pricing: Certain token options, such as Private Access tokens, may involve additional costs depending on the subscription package and access scope.
Usage Planning: Estimate expected AI interactions, query frequency, and automation volume to anticipate credit consumption.
Access Strategy: Consider separate credentials for different teams, customers, or workflows to support better usage management and administrative oversight.
ℹ️ Partner planning tip: Before deploying MCP integrations at scale, identify the workflows that require AI-driven access, estimate expected usage, and align credential allocation with operational needs and available subscription entitlements. This helps avoid unexpected consumption and supports more predictable costs.
Security and Risk Considerations
When choosing between REST API and MCP Server access, partners should evaluate the security requirements associated with each model, including credential management, access permissions, and data handling.
While both methods provide access to Liongard data, MCP integrations may introduce additional security considerations when connecting to third-party AI applications or automated agents.
REST API Security Considerations
Controlled Access: Suitable for traditional integrations and automated services with defined access requirements.
User-Based Permissions: Access is associated with a Liongard user identity, allowing permissions to be managed through existing user roles.
Credential Management: Supports conventional security practices, including secure credential storage, access reviews, and credential rotation.
MCP Server Security Considerations
Data Handling: Partners should understand how MCP clients process, store, and retain data retrieved from Liongard.
Third-Party Integrations: AI assistants and external MCP-compatible applications may introduce additional data privacy and security considerations.
Credential Governance: MCP credentials should have clearly defined ownership, appropriate access scopes, and established review and revocation procedures.
Environment Access: Partners should validate environment restrictions to ensure integrations access only the intended Liongard data.
Recommended Security Practices
Partners should follow these security practices for both access models:
Store API and MCP credentials in an approved secret management solution.
Avoid exposing credentials in documentation, chat messages, source code, or publicly accessible repositories.
Apply the principle of least privilege and review access regularly.
Configure credential expiration and rotation where supported.
Revoke credentials immediately when compromised or no longer required.
⚠️ Important: For MCP integrations, partners should evaluate not only how access to Liongard is authenticated and authorized, but also how retrieved data is handled by the connected AI client, including any third-party processing, storage, or retention policies.
Recommended Partner Implementation Patterns
Partners should select the appropriate Liongard access model based on their integration requirements, intended workflows, and security considerations. The following patterns provide guidance for common implementation scenarios.
Implementation Pattern | Best Suited For | Recommended Access Model | Best Practices |
Operational Integrations | Scheduled data synchronization, reporting, exports, and middleware integrations. | REST API | Use a dedicated integration identity where possible and manage credentials securely. |
Internal AI Workflows | Technician copilots, engineering analysis, troubleshooting, and internal AI-assisted operations. | MCP Server | Use securely managed MCP credentials, define appropriate environment access, and review usage regularly. |
Co-Managed Customer Access | AI-assisted workflows supporting specific customers or delegated service environments. | MCP Server (Restricted Access) | Apply the narrowest supported environment scope and validate access boundaries before deployment. |
Hybrid Integrations | Partners combining traditional API integrations with AI-powered workflows. | REST API + MCP Server | Maintain separate credentials, ownership, and access review processes for each model. |
ℹ️ Recommendation: Partners should use the REST API for structured, system-to-system integrations and the MCP Server for supported AI-driven workflows. When both models are required, manage their credentials, permissions, and access scopes independently to maintain appropriate security and governance.
Common Partner Questions
What is the difference between the Liongard REST API and MCP Server?
What is the difference between the Liongard REST API and MCP Server?
The REST API is designed for traditional integrations, automation, and structured data exchange. The MCP Server enables AI assistants and agent-based applications to interact with supported Liongard capabilities through the Model Context Protocol.
Can REST API credentials be used to authenticate with the MCP Server?
Can REST API credentials be used to authenticate with the MCP Server?
No. REST API and MCP Server credentials use separate authentication models and are not interchangeable. Partners must use the appropriate credentials and authentication method for each endpoint.
Can the MCP Server replace the REST API for all integrations?
Can the MCP Server replace the REST API for all integrations?
No. The MCP Server is intended for AI-driven workflows, while the REST API remains the recommended option for scheduled automation, reporting, system integrations, and structured data exchange.
How do permissions differ between REST API and MCP Server access?
How do permissions differ between REST API and MCP Server access?
REST API access follows the permissions associated with the underlying Liongard user account. MCP Server access uses a separate credential and configuration model and does not automatically inherit individual user permissions in the same way.
Can partners restrict MCP Server access to specific environments?
Can partners restrict MCP Server access to specific environments?
Yes. Liongard's MCP credential configuration includes optional environment selection. Partners should select the appropriate environments and validate that the configured restrictions are enforced before deployment.
What happens if the Liongard user associated with a REST API credential is disabled?
What happens if the Liongard user associated with a REST API credential is disabled?
Because REST API access is associated with a Liongard user identity, disabling the user will prevent continued authorized access through that identity.
Can multiple AI applications use the same MCP credential?
Can multiple AI applications use the same MCP credential?
Partners should preferably create separate MCP credentials for different applications or workflows. This helps maintain clear ownership, simplifies credential rotation, and allows access to be managed independently.
When should partners consider OAuth for MCP authentication?
When should partners consider OAuth for MCP authentication?
OAuth should be considered when supported by the MCP client and integration workflow. It can provide a more controlled authentication process and reduce the need to distribute static credentials.
Does MCP Server usage involve additional costs?
Does MCP Server usage involve additional costs?
MCP usage follows the applicable subscription and credit-based consumption model. Certain credential options, such as Private Access tokens, may involve additional costs depending on the partner's subscription and packaging.
Partners are advised to review their entitlements and anticipated usage prior to deployment. Please contact your Account Manager for further information or to clarify any questions you may have.
How can partners monitor and manage MCP credit consumption?
How can partners monitor and manage MCP credit consumption?
Partners can monitor their MCP credit consumption directly within the Liongard platform by navigating to:
Profile Name → Company Settings → Company Info → AI Insights
The AI Insights section provides visibility into available credit usage information, helping partners track consumption and manage their AI-related activities.
Partners should also consider their expected query frequency, AI workflow volume, and integration usage when planning credit consumption to avoid unexpected costs.
Does the MCP Server support the same operations and data as the REST API?
Does the MCP Server support the same operations and data as the REST API?
Not necessarily. The REST API and MCP Server expose capabilities through different interfaces. Partners should review the supported MCP tools and functionality rather than assuming that every REST API endpoint has an equivalent MCP operation.
What security considerations apply when connecting third-party AI assistants to Liongard?
What security considerations apply when connecting third-party AI assistants to Liongard?
Partners should evaluate how the AI client processes, stores, and retains retrieved Liongard data. They should also verify credential security, environment access restrictions, third-party privacy policies, and applicable customer data-handling requirements.
What should partners do if REST API or MCP authentication fails?
What should partners do if REST API or MCP authentication fails?
Partners should verify that they are using the correct endpoint, authentication method, and credentials for the selected access model.
They should also confirm that credentials are active, properly configured, and authorized for the intended operation. For MCP integrations, partners should additionally verify client configuration and environment access settings.
What are the recommended practices for managing REST API and MCP credentials?
What are the recommended practices for managing REST API and MCP credentials?
Partners should follow established security and credential governance practices, including:
Store credentials securely using an approved secret-management solution.
Assign clear ownership to each integration.
Apply the principle of least privilege.
Use separate credentials for different applications or workflows where practical.
Review access permissions and environment scope periodically.
Rotate credentials according to organizational security policies.
Revoke credentials immediately when compromised or no longer required.
✅ Recommendation: Partners should evaluate the integration's purpose, authentication requirements, access scope, security considerations, and expected usage before selecting either the REST API or MCP Server.
Do REST API keys automatically reflect changes to the creating user's permissions?
Do REST API keys automatically reflect changes to the creating user's permissions?
Yes. REST API keys inherit the current role, permissions, and environment access of the Liongard user who generated them. These permissions are not permanently fixed when the key is created.
For example:
Role Changes: If a user's role changes from Administrator to Manager, the API key automatically follows the permissions associated with the Manager role.
Environment Restrictions: Example : If a user initially has access to 15 environments but is later restricted to 10, the API key will also be limited to those 10 environments.
⚠️ Important: REST API keys follow the user's current access permissions rather than retaining the permissions assigned at the time of creation. The exact propagation delay for permission changes is not specified here.
Can MCP credentials authenticate against Liongard REST API v1 or v2 endpoints?
Can MCP credentials authenticate against Liongard REST API v1 or v2 endpoints?
No. MCP credentials are designed exclusively for Liongard's MCP Server endpoint (/api/mcp) using Bearer token authentication.
They cannot be used to authenticate against standard REST API v1 or v2 endpoints using the X-ROAR-API-KEY header.
Partners must use the appropriate credentials and authentication method for each access model.
Are MCP credentials read-only, or do they inherit the creating user's write permissions?
Are MCP credentials read-only, or do they inherit the creating user's write permissions?
MCP credentials do not inherit the creating user's permissions.
MCP Server tools are currently focused on retrieving and analyzing Liongard data, including environments, systems, assets, timelines, detections, and metrics.
Administrative write operations and platform configuration changes are not exposed through the current MCP toolset.
Do MCP credentials continue working if the creating user's role changes or account is disabled?
Do MCP credentials continue working if the creating user's role changes or account is disabled?
Are newly created environments automatically accessible through an environment-scoped MCP credential?
Are newly created environments automatically accessible through an environment-scoped MCP credential?
This depends on how the credential is configured:
All Environments: Newly created environments are automatically included.
Specific Environments: Only explicitly selected environments are accessible. New environments must be added to the credential's scope.
Environment Groups: Access follows the configured environment group scope, subject to the platform's group membership enforcement behavior.
Partners should verify group membership updates before relying on automatic access changes in production.
Can MCP credentials be configured to access all environments except specific exclusions?
Can MCP credentials be configured to access all environments except specific exclusions?
No. MCP credentials do not currently support an exclusion-based rule such as "all environments except these."
Partners can configure access to all environments or explicitly select the environments or environment groups that should be accessible.
Does Liongard support environment-group scoping for MCP credentials?
Does Liongard support environment-group scoping for MCP credentials?
Yes. MCP credential creation supports two environment-scoping options:
Environment Groups: Select existing environment groups configured in Liongard.
Individual Environments: Select specific environments individually.
If additional environment groups are required, administrators can create them by navigating to: Admin → Access Management → Environment Group
This allows partners to organize environments into logical groups and use those groups when configuring MCP access.
Does restricting an MCP credential to specific environments or environment groups incur additional charges?
Does restricting an MCP credential to specific environments or environment groups incur additional charges?
No. Environment scoping itself does not incur additional charges under the MCP subscription.
Partners can create multiple standard operational MCP tokens without additional token fees, regardless of whether they are:
Unscoped, with access to all environments.
Restricted to selected environments.
Scoped to configured environment groups.