Guides / Intelligence
Connect an AI client to your project over MCP
Follow this guide to let an AI client, such as an assistant or an IDE, work with your project. The client gets two tools. One finds out what your API offers, and the other runs a GraphQL document against it. The client acts as a service account you choose, so it can never do more than that account may. Every call is recorded.
Access is by invitation. To ask for it, write to us.
1. Make the account the client acts as
Give the account the narrowest role that works, and start with a read-only one. The endpoint is also read-only unless you turn that off, but the hard limit is always the account's own rights, whatever the client asks for.
kubectl apply -f - <<EOF
apiVersion: iam.etorm.com/v1alpha1
kind: ServiceAccount
metadata: {name: assistant}
---
apiVersion: iam.etorm.com/v1alpha1
kind: RoleBinding
metadata: {name: assistant}
spec:
roleRef: {name: viewer}
subjects: [{kind: ServiceAccount, name: assistant}]
EOF
You need the right to act as the account yourself, which project owners have. Without it you cannot make an endpoint or a credential for the account.
2. Create the endpoint
kubectl apply -f - <<EOF
apiVersion: intelligence.etorm.com/v1alpha1
kind: MCPEndpoint
metadata: {name: assistant}
spec:
serviceAccountRef: {name: assistant}
description: "Read-only view for my assistant"
allow: {groups: [network.etorm.com, compute.etorm.com]}
retentionDays: 30
EOF
Without allow, the endpoint reaches every group the account may use, except identity and access, secrets, billing and projects. Those are reachable only when you name them. readOnly is true unless you set it to false. When the endpoint is Ready, status.url is the address to connect to.
3. Make a credential for the client
kubectl apply -f - <<EOF
apiVersion: intelligence.etorm.com/v1alpha1
kind: MCPCredential
metadata: {name: assistant-laptop}
spec:
endpointRef: {name: assistant}
description: "my laptop"
expiresAt: "2027-01-31T00:00:00Z"
EOF
The response carries status.token once. We keep only a hash, so we cannot show the token to you again. In the console the token and the client configuration are shown on a page of their own. The token works on this endpoint and nowhere else in the API.
4. Configure the client
Any client that speaks MCP over Streamable HTTP takes the address and the token:
{"mcpServers": {"assistant": {"type": "http", "url": "https://mcp.etorm.com/<project>/assistant", "headers": {"Authorization": "Bearer <token>"}}}}
What the two tools do
search takes words ("virtual private network cidr") and returns only the matching kinds, with their fields as GraphQL types and an example, so the client never has to read your whole schema. execute takes one GraphQL document and optional variables and runs it as the account:
{ network { vpcs(first: 10) { items { metadata { name } spec { cidr } status { phase } } total } } }
While the endpoint is read-only, calls that create, change or delete are refused. Anything the account may not do is refused by the API, as for any other call. You can also use the same GraphQL API directly at POST /clusters/<project>/graphql.
Reach a whole workspace
To let one document read every project below a workspace that the account may use, add workspaceRef: {name: <workspace>} to the endpoint. The endpoint must live in a project of that workspace or below it, and you need to be able to see the workspace. Objects then carry their project and workspace, and changes name the project they act in. To make the account a workspace-level one, give the service account of that project a role binding scoped to the workspace.
What is recorded
Every tool call is recorded as an MCPCall object. It holds the tool, a hash of the document and its operation name, what it touched, who asked (the client's own name), how it ended and how large the answer was. The text of a document and its result are not kept, and no secret ever is. Changes also appear in your audit log under the account's name. Records are kept for retentionDays.
Rotate or revoke a credential
To rotate, make a second credential, move the client to it, then delete the first. The first stops working at its next call. To cut a client off, delete or disable its credential. Disabling the endpoint, or the account, ends every session at once.