Skip to main content

AI Client Connection Guide (MCP)

How to connect MCP-capable AI clients to the MCP of AGENTIC STAR. With the chat set, you ask an agent to do work; with the project set, you create and run projects with registered agents, handle approval requests, and more. For detailed tool specifications, see the MCP API Reference.

Before you start

MCP is available only in environments where an administrator has opened the MCP inbound endpoint. For a person to connect with their own account, the entrance for sign-in from an external tool must also be open (API Setup Guide).

What You Need​

  • The AI client you use (Claude Code, Codex, Cursor, or VS Code)
  • To connect as a person: the client ID of an external tool client that an administrator created in the authorization server console
  • To connect as a system integration: a service account that an administrator created in the admin screen (client ID and client secret)
  • The address of the environment's external API entrance (<your-domain>) and of the authorization server's external entrance (<auth-domain>)

Install the Plugin (Recommended)​

You can install the AGENTIC STAR plugin in Claude Code and Codex. After installing it, ask "Connect to AGENTIC STAR", and it guides you through the connection.

IncludedWhat it does
agenticstar-connectGuides you through connecting to the AGENTIC STAR MCP
agenticstar-projectsCreates projects with registered agents, finds out why runs failed, handles approval requests, and reads results
  • The plugin does not include MCP connection settings. Set your client ID and other values by following its guidance
  • It is a different plugin from the SaaS edition's. For the Marketplace edition, use the plugin on this page
  • Current version: 3.2.0

Download the plugin (agenticstar-mp.zip)

In the folder where you extracted the zip, run the following (Claude Code 2.1.292 or later).

curl
claude plugin install agenticstar-mp --marketplace ./agenticstar-mp

Choose How to Connect​

Who uses itHow to connectWhat to prepare
A person (with their own account)Sign in with the clientAn external tool client (client ID)
A system (system integration)Put a token obtained with the Client Credentials flow in Authorization: BearerA service account (client ID and client secret)

The MCP endpoint is as follows. Select the tool sets with toolsets (Tool Sets). To also call published workflows, add published.

https://<your-domain>/api/v1/mcp?toolsets=chat,project

External tools do not choose scopes. When a person connects, the external tool can do what that person can do on the Main Screen.

About the configuration examples

The settings on this page are examples for reference. How to configure a client can change between its versions. For the latest instructions, see each client's documentation (Claude Code, Codex, Cursor, VS Code). For other MCP clients, set the endpoint and client ID by following that client's documentation.

Trying It in an Environment without a Domain​

In an environment where no domain and certificate are set (the default state), the entrances use a self-signed certificate created by the product. External tools do not trust this certificate, so they cannot connect as is. To try connecting in the default state, do the following. The browser that opens for sign-in also shows a certificate warning.

Claude Code​

Start Claude Code with certificate verification turned off.

curl
NODE_TLS_REJECT_UNAUTHORIZED=0 claude

With verification turned off, you cannot notice if the communication is intercepted or altered. Use it only while trying, and only for that launch.

Codex​

Get the certificate of the entrance and make Codex trust it.

  1. Save the certificate of the entrance to a file (<your-domain> is the address of the external API entrance)

    curl
    openssl s_client -connect <your-domain>:443 -showcerts < /dev/null | openssl x509 > agentic-star.crt
  2. Set the path of the saved file in the environment variable CODEX_CA_CERTIFICATE, and then start Codex (before codex mcp login)

    curl
    export CODEX_CA_CERTIFICATE="$PWD/agentic-star.crt"

The certificate changes when it is recreated (it is valid for 365 days, and it is also recreated when the entrance for sign-in from an external tool is opened). If you can no longer connect, get the certificate again.

Cursor and VS Code​

They cannot connect in this state. Cursor stays at "Connecting..." without showing the reason, and VS Code shows unable to verify the first certificate. Set up a domain and certificate before using them.

Before Starting Regular Operation​

Always set a domain and a certificate. Once they are set, neither setting is needed (Domain Settings Guide).

Connect as a Person​

1. Prepare an External Tool Client​

An administrator creates a client in the authorization server console by following API Setup Guide — Creating an External Tool Client. Register http://localhost/callback and http://127.0.0.1/callback as the redirect URIs. Register http://127.0.0.1/ as well when you use VS Code. The port is not checked, so you can choose any free port for the clients below.

2. Configure the Client and Sign In​

Replace <client_id> with the client ID of the client you created.

curl
claude mcp add --scope user --transport http \
--client-id <client_id> --callback-port <port> \
agenticstar 'https://<your-domain>/api/v1/mcp?toolsets=chat,project'

Open /mcp in Claude Code and choose to authenticate agenticstar, or run claude mcp login agenticstar. The sign-in page opens in the browser.

Connect as a System Integration​

  1. Create a service account in the admin screen by following API Setup Guide — Creating a System Integration
  2. Get an access token from https://<auth-domain>/api/v1/oauth/token with the Authentication Guide — Client Credentials flow
  3. Set Authorization: Bearer <access_token> in the client. When the token expires, get a new one in the same way and set it again (Refreshing a Token)
curl
claude mcp add --scope user --transport http agenticstar-system \
'https://<your-domain>/api/v1/mcp?toolsets=chat,project' \
--header "Authorization: Bearer <access_token>"

A system integration can use the tools of the chat set, four operations of the project set (list of project_read, get of run_read, start_run and fire_trigger of project_run), and the tools of the published set. A system integration's token can work with all projects in this environment.

Use It Safely​

  • Operations that write: When you let the AI create, change, or delete projects, or decide approval requests, use the client's permission settings so that you can check each operation before it runs (Claude Code asks for permission every time before it decides an approval request. For other clients, see the client's documentation)
  • Tokens and secrets: Treat access tokens and client secrets as secrets. Don't paste them into chats or documents
  • Stopping an external tool: An external tool that has signed in does not stop when you sign out of the Main Screen. For how to stop it, see API Setup Guide — Stopping an External Tool
  • If credentials leak: Disable the service account or regenerate the client secret in the admin screen (API Setup Guide — If Credentials Leak)

Troubleshooting​

  • Every call returns 404: The MCP inbound endpoint, or the entrance for sign-in from an external tool, is not open in this environment. Ask your administrator
  • Certificate errors: See Trying It in an Environment without a Domain
  • Tool sets: Without toolsets, only the chat set is available. Specify project for the project set, and published to call published workflows
  • Sign-in is refused: Accounts waiting for approval and accounts whose email address is not confirmed cannot sign in from an external tool. Get the account approved first
  • Rejected for a system integration: This endpoint is not available to client credentials (403) is returned when a system integration calls an operation it cannot use. To use that operation, connect as a person
  • When the tools change: When an AGENTIC STAR update changes the tools, reconnect (in Claude Code, /mcp)

See Also​