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.
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.
| Included | What it does |
|---|---|
agenticstar-connect | Guides you through connecting to the AGENTIC STAR MCP |
agenticstar-projects | Creates 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)
- Claude Code
- Codex
In the folder where you extracted the zip, run the following (Claude Code 2.1.292 or later).
claude plugin install agenticstar-mp --marketplace ./agenticstar-mp
In the folder where you extracted the zip, run the following.
codex plugin marketplace add ./agenticstar-mp
codex plugin add agenticstar-mp@agenticstar-mp
Codex reads the plugin's instructions with the shell. Use it with the shell available.
Choose How to Connect
| Who uses it | How to connect | What to prepare |
|---|---|---|
| A person (with their own account) | Sign in with the client | An external tool client (client ID) |
| A system (system integration) | Put a token obtained with the Client Credentials flow in Authorization: Bearer | A 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.
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.
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.
-
Save the certificate of the entrance to a file (
<your-domain>is the address of the external API entrance)curlopenssl s_client -connect <your-domain>:443 -showcerts < /dev/null | openssl x509 > agentic-star.crt -
Set the path of the saved file in the environment variable
CODEX_CA_CERTIFICATE, and then start Codex (beforecodex mcp login)curlexport 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.
- Claude Code
- Codex
- Cursor
- VS Code
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.
Add the following to ~/.codex/config.toml.
[mcp_servers.agenticstar]
url = "https://<your-domain>/api/v1/mcp?toolsets=chat,project"
scopes = ["openid"]
[mcp_servers.agenticstar.oauth]
client_id = "<client_id>"
callback_port = <port>
callback_url = "http://localhost:<port>/callback"
Run codex mcp login agenticstar. The sign-in page opens in the browser. Don't omit scopes = ["openid"]. Without it, Codex requests every scope that the authorization server advertises, and the sign-in is refused with invalid_scope.
Add the following to .cursor/mcp.json in your project (or ~/.cursor/mcp.json).
{
"mcpServers": {
"agenticstar": {
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"auth": {
"CLIENT_ID": "<client_id>"
}
}
}
}
Enable agenticstar in the MCP list on the Customize page in the sidebar, and continue when asked to sign in. A server written in the project's .cursor/mcp.json is available in chats started in that project.
Add the following to .vscode/mcp.json in your workspace.
{
"servers": {
"agenticstar": {
"type": "http",
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"oauth": {
"clientId": "<client_id>"
}
}
}
}
Start the server from "MCP: List Servers" in the Command Palette. The sign-in page opens in the browser.
- To use the tools from chat, VS Code chat (GitHub Copilot) must be available
- Set Session Target in the chat input to Local. Other harnesses (such as Copilot) do not receive this configuration and cannot connect
Connect as a System Integration
- Create a service account in the admin screen by following API Setup Guide — Creating a System Integration
- Get an access token from
https://<auth-domain>/api/v1/oauth/tokenwith the Authentication Guide — Client Credentials flow - 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)
- Claude Code
- Codex
- Cursor
- VS Code
claude mcp add --scope user --transport http agenticstar-system \
'https://<your-domain>/api/v1/mcp?toolsets=chat,project' \
--header "Authorization: Bearer <access_token>"
Put the token in the environment variable AGENTICSTAR_TOKEN, and add the following to ~/.codex/config.toml.
[mcp_servers.agenticstar-system]
url = "https://<your-domain>/api/v1/mcp?toolsets=chat,project"
bearer_token_env_var = "AGENTICSTAR_TOKEN"
{
"mcpServers": {
"agenticstar-system": {
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"headers": {
"Authorization": "Bearer <access_token>"
}
}
}
}
{
"inputs": [
{ "type": "promptString", "id": "agenticstar-token", "description": "AGENTIC STAR access token", "password": true }
],
"servers": {
"agenticstar-system": {
"type": "http",
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"headers": {
"Authorization": "Bearer ${input:agenticstar-token}"
}
}
}
}
Set Session Target in the chat input to Local. Servers that use ${input:…} are not passed to other harnesses (such as Copilot).
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. Specifyprojectfor the project set, andpublishedto 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
- MCP API Reference — Tool and error specifications
- Authentication Guide — Getting tokens
- API Setup Guide — Creating external tool clients and service accounts
- Connection Methods Guide — Choosing between REST, MCP, and A2A