Responsibilities of Skills, MCP, CLIs, and APIs

When we build AI-enabled developer experiences, it is important to be clear about which layer is responsible for what. Skills, MCP servers, CLIs, and APIs can work together, but they should not all do the same job. Each layer has a different responsibility, especially when authentication and user permissions are involved.

The simplest way to think about it is this:

Skills describe how work should be done.

MCP servers perform authenticated actions.

CLIs support developer-controlled local workflows.

APIs expose product capabilities with proper authorization.

Skills: the workflow and instruction layer

Skills are best used to teach an AI system how to work in a specific domain.

A Skill can contain:

• product knowledge

• workflow instructions

• best practices

• validation rules

• examples

• templates

• decision trees

• conventions for how work should be done

A Skill should help the model understand the task and guide the user or system toward the correct outcome.

For example, a Contentstack Skill might explain how to plan a Studio project, what files should be generated, how to structure content models, or what checks should happen before publishing.

A Skill should not be responsible for holding access tokens, storing credentials, or directly calling authenticated APIs as the user.

If a Skill receives an access token, it effectively becomes an authenticated integration layer. That creates security, governance, auditability, and ownership problems.

A good rule of thumb: A Skill can request authenticated work, but it should not become the authenticated actor.

MCP: the authenticated tool execution layer

MCP is the right place for AI-accessible tools that perform real actions.

An MCP server can expose a focused set of tools to an AI system, such as:

• list stacks

• create a Studio project

• fetch content types

• create branches

• install apps

• validate project setup

• generate environment configuration

The MCP server owns the execution boundary. It can handle authentication, scopes, authorization, token storage, rate limits, logging, and auditing.

This is especially important because AI systems should not need broad raw API access. They should get specific, well-named tools that perform intentional actions.

Instead of giving the model a generic token and saying “call whatever APIs you need,” we expose a tool like:

create_studio_project

That tool can validate inputs, call the right APIs, enforce permissions, and return a safe result.

A good rule of thumb:

MCP turns user intent into controlled, authenticated actions.

CLI: the developer-controlled local workflow layer

A CLI is a developer-facing tool. It is useful when the user is intentionally working in their local environment or terminal.

A CLI can:

• log a user in

• store local auth state securely

• scaffold files

• run setup commands

• create projects

• validate local configuration

• call APIs on behalf of the user

• connect local development workflows to Contentstack

The CLI is a good place for workflows where the developer is actively in control.

For example:

contentstack login
contentstack studio create-project
contentstack app scaffold
contentstack mcp --auth

However, CLI authentication should stay inside the CLI or the runtime it is explicitly authenticating. A CLI should not expose reusable session tokens to Skills or other layers just because they want to perform authenticated work.

A good rule of thumb:

The CLI may authenticate the developer, but it should not leak reusable credentials into instruction layers.

APIs: the product capability layer

APIs expose the actual product capabilities. They are the system of record for what can be done.

APIs should provide:

• clear permissions

• OAuth support where needed

• scoped access

• stable contracts

• validation

• auditability

• predictable error handling

• product-level authorization

If an AI workflow needs to create a Studio project, install an app, or modify resources, the APIs need to support that flow with the correct auth model.

If the required APIs do not yet support the right OAuth or authorization pattern, the solution should be to improve the API/auth model or expose the right capability through MCP or CLI. The solution should not be to pass around a session token from another layer.

A good rule of thumb:

APIs define what is possible and enforce who is allowed to do it.

How these layers should work together

A healthy flow looks like this:

1. The Skill explains the workflow.

2. The user asks the AI system to perform a task.

3. The AI system calls a focused MCP tool.

4. The MCP server handles auth and calls the required APIs.

5. The APIs enforce permissions and perform the action.

6. The result is returned to the user.

For local developer workflows, the flow may look like this:

1. The user runs a CLI command.

2. The CLI uses its own authenticated context.

3. The CLI calls the required APIs.

4. The CLI writes files, creates projects, or validates setup locally.

Both patterns are valid. What we should avoid is mixing responsibilities in a way that weakens the security model.

What we should avoid

We should avoid patterns like:

• exposing MCP session tokens to Skills

• letting Skills store or reuse access tokens

• giving AI systems raw bearer tokens

• bypassing OAuth because another layer already has a session

• using Skills as hidden API clients

• treating CLI auth as a general-purpose token vending mechanism

• creating one-off shortcuts that are hard to govern later

These patterns may solve a short-term integration problem, but they create long-term risk.

They make it harder to answer basic questions like:

• Who is the authenticated actor?

• Which scopes were granted?

• Where is the token stored?

• Can the token be revoked?

• What actions can this layer perform?

• Can we audit what happened?

• Can we safely expose this to customers or partners?

If those questions are hard to answer, the boundary is probably wrong.

Recommended ownership model

For Contentstack developer and AI surfaces, the responsibility split should be:

Practical principle

When designing a new feature or integration, ask:

Is this layer describing the work, executing the work, or authorizing the work?

• If it is describing the work, it belongs in a Skill.

• If it is executing authenticated work on behalf of an AI system, it belongs in MCP.

• If it is executing developer-controlled local work, it belongs in the CLI.

• If it is defining product capability and permissions, it belongs in the API.

Keeping these boundaries clear helps us build AI experiences that are powerful, secure, supportable, and easier to explain.